(Introduced in OCaml 4.03)
Comments which start with ** are treated specially by the compiler. They are automatically converted during parsing into attributes (see 12.12) to allow tools to process them as documentation.
Such comments can take three forms: floating comments, item comments and label comments. Any comment starting with ** which does not match one of these forms will cause the compiler to emit warning 50.
Comments which start with ** are also used by the ocamldoc documentation generator (see 19). The three comment forms recognised by the compiler are a subset of the forms accepted by ocamldoc (see 19.2).
Comments surrounded by blank lines that appear within structures, signatures, classes or class types are converted into floating-attributes. For example:
will be converted to:
Comments which appear immediately before or immediately after a structure item, signature item, class item or class type item are converted into item-attributes. Immediately before or immediately after means that there must be no blank lines, ;;, or other documentation comments between them. For example:
or
will be converted to:
Note that, if a comment appears immediately next to multiple items, as in:
then it will be attached to both items:
and the compiler will emit warning 50.
Comments which appear immediately after a labelled argument, record field, variant constructor, object method or polymorphic variant constructor are are converted into attributes. Immediately after means that there must be no blank lines or other documentation comments between them. For example:
will be converted to:
Note that label comments take precedence over item comments, so:
will be converted to:
whilst:
will be converted to:
In the absence of meaningful comment on the last constructor of a type, an empty comment (**) can be used instead:
will be converted directly to