8.19 Documentation comments

Comments which start with ** are treated specially by thecompiler. They are automatically converted during parsing intoattributes (see 8.13) to allow tools to process them asdocumentation.

Such comments can take three forms: floating comments, itemcomments and label comments. Any comment starting with ** whichdoes not match one of these forms will cause the compiler to emitwarning 50.

Comments which start with ** are also used by the ocamldocdocumentation generator (see 15). The three comment formsrecognised by the compiler are a subset of the forms accepted byocamldoc (see 15.2).

8.19.1 Floating comments

Comments surrounded by blank lines that appear within structures,signatures, classes or class types are converted intofloating-attributes. For example:

  1.  type t = T
  3.  (** Now some definitions for [t] *)
  5.  let mkT = T
  6.  

will be converted to:

  1.  type t = T
  3.  [@@@ocaml.text " Now some definitions for [t] "]
  5.  let mkT = T
  6.  

8.19.2 Item comments

Comments which appear immediately before or immediatelyafter a structure item, signature item, class item or class type itemare converted into item-attributes. Immediately before or immediatelyafter means that there must be no blank lines, ;;, or otherdocumentation comments between them. For example:

  1.  type t = T
  2.  (** A description of [t] *)
  4.  

or

  1.  (** A description of [t] *)
  2.  type t = T
  3.  

will be converted to:

  1.  type t = T
  2.  [@@ocaml.doc " A description of [t] "]
  3.  

Note that, if a comment appears immediately next to multiple items,as in:

  1.  type t = T
  2.  (** An ambiguous comment *)
  3.  type s = S
  4.  

then it will be attached to both items:

  1.  type t = T
  2.  [@@ocaml.doc " An ambiguous comment "]
  3.  type s = S
  4.  [@@ocaml.doc " An ambiguous comment "]
  5.  

and the compiler will emit warning 50.

8.19.3 Label comments

Comments which appear immediately after a labelled argument,record field, variant constructor, object method or polymorphic variantconstructor are are converted into attributes. Immediatelyafter means that there must be no blank lines or other documentationcomments between them. For example:

  1.  type t1 = lbl:int (** Labelled argument *) -> unit
  3.  type t2 = {
  4.    fld: int; (** Record field *)
  5.    fld2: float;
  6.  }
  8.  type t3 =
  9.    | Cstr of string (** Variant constructor *)
  10.    | Cstr2 of string
  12.  type t4 = < meth: int * int; (** Object method *) >
  14.  type t5 = [
  15.    `PCstr (** Polymorphic variant constructor *)
  16.  ]
  17.  

will be converted to:

  1.  type t1 = lbl:(int [@ocaml.doc " Labelled argument "]) -> unit
  3.  type t2 = {
  4.    fld: int [@ocaml.doc " Record field "];
  5.    fld2: float;
  6.  }
  8.  type t3 =
  9.    | Cstr of string [@ocaml.doc " Variant constructor "]
  10.    | Cstr2 of string
  12.  type t4 = < meth : int * int [@ocaml.doc " Object method "] >
  14.  type t5 = [
  15.    `PCstr [@ocaml.doc " Polymorphic variant constructor "]
  16.  ]
  17.  

Note that label comments take precedence over item comments, so:

  1.  type t = T of string
  2.  (** Attaches to T not t *)
  3.  

will be converted to:

  1.  type t =  T of string [@ocaml.doc " Attaches to T not t "]
  2.  

whilst:

  1.  type t = T of string
  2.  (** Attaches to T not t *)
  3.  (** Attaches to t *)
  4.  

will be converted to:

  1.  type t =  T of string [@ocaml.doc " Attaches to T not t "]
  2.  [@@ocaml.doc " Attaches to t "]
  3.  

In the absence of meaningful comment on the last constructor ofa type, an empty comment (**) can be used instead:

  1.  type t = T of string
  2.  (**)
  3.  (** Attaches to t *)
  4.  

will be converted directly to

  1.  type t =  T of string
  2.  [@@ocaml.doc " Attaches to t "]
  3.