Document how to write documentation for modules #644
Conversation
This documentation is targeted at Odoc's users writing documentation for their modules.
Add a summary and the "comments" section. Co-authored-by: Jon Ludlam <jon@recoil.org>
src/odoc/using-odoc.mld
Outdated
| {2 Preamble} | ||
|
|
||
| The preamble is composed of the comment attached to a declaration and the | ||
| top-comment of the expansion. |
There was a problem hiding this comment.
The notion of expansion is not explained before this occurence. I'm personally unclear to what it refers to. Could you maybe expand on that ?
There was a problem hiding this comment.
I think I've managed to remove that word, it isn't necessary in the documentation. I meant the sig ... end part when there is one.
src/odoc/using-odoc.mld
Outdated
| {[ | ||
| (** This is the comment attached to the declaration. *) | ||
| module M : sig | ||
| (** This is the top-comment of the expansion. *) |
There was a problem hiding this comment.
Just to make things clear. What is the synopsis and preamble here ? My expectation is that the outer comment gets merged with the second with a blank line between them (i.e. there are two paragraphs here).
src/odoc/using-odoc.mld
Outdated
| end | ||
| ]} | ||
|
|
||
| The comment attached to the declaration shouldn't contain any heading. |
There was a problem hiding this comment.
I understand what you mean here, but I'm not sure it's very clear. Maybe this would be better said around an example that has a comment attached to the declaration.
There was a problem hiding this comment.
Maybe I can drop this sentence ? It's not related to the example, it's an aside saying the thing described above doesn't happen with decl comments.
src/odoc/using-odoc.mld
Outdated
| The synopsis of a module (a module type, a class, etc..) is the first | ||
| paragraph of the {!preamble}, {e if} the preamble starts with a paragraph. | ||
|
|
||
| It is rendered near declarations and in [{!modules:...}] lists. |
There was a problem hiding this comment.
near declarations -> after module declarations
|
|
||
| {[ | ||
| module M : sig | ||
| (** This paragraph is the synopsis of the module [M]. *) |
There was a problem hiding this comment.
Here again might be worth indicating what happens when you have:
(** Bli bla *)
module M : sig
(** Hey ho *)
endThere was a problem hiding this comment.
There is an other before that covering this case. This example comes in pair, maybe I should merge them in a single block and call my modules M and N ?
From dbuenzli.
|
|
||
| The documentation can be formatted, Odoc accepts the same markup language as | ||
| {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#s%3Aocamldoc-comments} | ||
| ocamldoc} with some exceptions, see {!page-interface.Changes}. |
There was a problem hiding this comment.
This is not the topic of this PR, but I think we should just include the markup language documentation in our documentation, and only just say "this is based on the ocamldoc one".
The
preambleandsynopsisparts describe the current state of #640 and #643