Introduce `rustredoc`
What?
rustredoc
is to Lustre what rustdoc
is to Rust. A documentation tool.
lustredoc
?
Why not Lustre doesn't have an official documentation tool. We would have to invent our own standard/format for the doc comments, and we wouldn't want users to believe that this has anything to do with the official Lustre tools. Also, the tool would most likely be invoked as rustre doc
rather than a specific rustredoc
command, so it just makes sense to not call it lustredoc
.
Goal
Ability to generate documentation given one or many Lustre files (including dependencies), in HTML or PDF format (Pandoc?). The documentation would give the details of
- each module that was found
- each nodes/functions defined in them (name, signature, statefulness, acceptability of null values) with an added custom documentation text
- typedefs, structs, enums
- external nodes/functions
The documentation could include additional Lustre-specific information, e.g.:
- A (visual) graph of a node's implementation
- For pure nodes that emit a stream of data, independent of the input, a computed series of the first values, as an example
These would be opt-in, enabled through special documentation directives (see below paragraphs).
Documenting within the code
Like rustdoc, javadoc, doxygen, etc., we would expect the code to be documented internally, by adding special comments before documented items. These comments could add a description of the item, and additional directives to customize what information is rendered exactly, and how.
As said previously, Lustre doesn't have an official doc format, and it's thus our responsibility to invent our own. Since Lustre is very tied to OCaml, it would make sense to take inspiration from OCaml's own doc tool. As such I propose the syntax (** *)
to denote documentation comments. Because Lustre also has C-style comments, these should also work (/** */
) to have parity with Javadoc/Doxygen.
- The indent removal should work the same way as OCaml, which I guess just ignores preceding whitespace on each line withing doc comments (we should check). The content of doc comments should support as much of the markdown syntax as possible. Language-specific features, such as intra links, are desirable: Rustdoc has a nice approach to them which feels very Markdown-y.
- It should be possible to write brief single-line comments (e.g.
(** Returns the negation of the given boolean value *)
- Like Rustdoc, it'd be nice to not rely too much on directives. The first paragraph could also be implicitly used as a brief summary.
TODO
-
Define the doc format clearly -
Implement at least one backend -
Improve this issue