15.2 Syntax of documentation comments

15.2.1. Placement of documentation comments
15.2.2. The Stop special comment
15.2.3. Syntax of documentation comments
15.2.4. Text formatting
15.2.5. Documentation tags (@-tags)

Comments containing documentation material are called special comments and are written between (** and *). Special comments must start exactly with (**. Comments beginning with ( and more than two * are ignored.

15.2.1 Placement of documentation comments

OCamldoc can associate comments to some elements of the language encountered in the source files. The association is made according to the locations of comments with respect to the language elements. The locations of comments in .mli and .ml files are different.

Comments in .mli files

A special comment is associated to an element if it is placed before or after the element.

A special comment before an element is associated to this element if :

  • There is no blank line or another special comment between the special comment and the element. However, a regular comment can occur between the special comment and the element.
  • The special comment is not already associated to the previous element.
  • ~ The special comment is not the first one of a toplevel module.

A special comment after an element is associated to this element if there is no blank line or comment between the special comment and the element.

There are two exceptions: for type constructors and record fields in type definitions, the associated comment can only be placed after the constructor or field definition, without blank lines or other comments between them. The special comment for a type constructor with another type constructor following must be placed before the '|' character separating the two constructors.

The following sample interface file foo.mli illustrates the placement rules for comments in .mli files.

(** The first special comment of the file is the comment associated
    with the whole module.*)

(** Special comments can be placed between elements and are kept
    by the OCamldoc tool, but are not associated to any element.
    @-tags in these comments are ignored.*)

(*******************************************************************)
(** Comments like the one above, with more than two asterisks,
    are ignored. *)

(** The comment for function f. *)
val f : int -> int -> int
(** The continuation of the comment for function f. *)

(** Comment for exception My_exception, even with a simple comment
    between the special comment and the exception.*)
(* Hello, I'm a simple comment :-) *)
exception My_exception of (int -> int) * int

(** Comment for type weather  *)
type weather =
| Rain of int (** The comment for construtor Rain *)
| Sun (** The comment for constructor Sun *)

(** Comment for type weather2  *)
type weather2 =
| Rain of int (** The comment for construtor Rain *)
| Sun (** The comment for constructor Sun *)
(** I can continue the comment for type weather2 here
  because there is already a comment associated to the last constructor.*)

(** The comment for type my_record *)
type my_record = {
    val foo : int ;    (** Comment for field foo *)
    val bar : string ; (** Comment for field bar *)
  }
  (** Continuation of comment for type my_record *)

(** Comment for foo *)
val foo : string
(** This comment is associated to foo and not to bar. *)
val bar : string
(** This comment is assciated to bar. *)

(** The comment for class my_class *)
class my_class :
  object
    (** A comment to describe inheritance from cl *)
    inherit cl

    (** The comment for attribute tutu *)
    val mutable tutu : string

    (** The comment for attribute toto. *)
    val toto : int

    (** This comment is not attached to titi since
        there is a blank line before titi, but is kept
        as a comment in the class. *)

    val titi : string

    (** Comment for method toto *)
    method toto : string

    (** Comment for method m *)
    method m : float -> int
  end

(** The comment for the class type my_class_type *)
class type my_class_type =
  object
    (** The comment for variable x. *)
    val mutable x : int

    (** The commend for method m. *)
    method m : int -> int
end

(** The comment for module Foo *)
module Foo =
  struct
    (** The comment for x *)
    val x : int

    (** A special comment that is kept but not associated to any element *)
  end

(** The comment for module type my_module_type. *)
module type my_module_type =
  sig
    (** The comment for value x. *)
    val x : int

    (** The comment for module M. *)
    module M =
      struct
        (** The comment for value y. *)
        val y : int

        (* ... *)
      end

  end

Comments in .ml files

A special comment is associated to an element if it is placed before the element and there is no blank line between the comment and the element. Meanwhile, there can be a simple comment between the special comment and the element. There are two exceptions, for type constructors and record fields in type definitions, whose associated comment must be placed after the constructor or field definition, without blank line between them. The special comment for a type constructor with another type constructor following must be placed before the '|' character separating the two constructors.

The following example of file toto.ml shows where to place comments in a .ml file.

(** The first special comment of the file is the comment associated
    to the whole module.*)

(** The comment for function f *)
let f x y = x + y

(** This comment is not attached to any element since there is another
    special comment just before the next element. *)

(** Comment for exception My_exception, even with a simple comment
    between the special comment and the exception.*)
(* A simple comment. *)
exception My_exception of (int -> int) * int

(** Comment for type weather  *)
type weather =
| Rain of int (** The comment for constructor Rain *)
| Sun (** The comment for constructor Sun *)

(** The comment for type my_record *)
type my_record = {
    val foo : int ;    (** Comment for field foo *)
    val bar : string ; (** Comment for field bar *)
  }

(** The comment for class my_class *)
class my_class =
    object
      (** A comment to describe inheritance from cl *)
      inherit cl

      (** The comment for the instance variable tutu *)
      val mutable tutu = "tutu"
      (** The comment for toto *)
      val toto = 1
      val titi = "titi"
      (** Comment for method toto *)
      method toto = tutu ^ "!"
      (** Comment for method m *)
      method m (f : float) = 1
    end

(** The comment for class type my_class_type *)
class type my_class_type =
  object
    (** The comment for the instance variable x. *)
    val mutable x : int
    (** The commend for method m. *)
    method m : int -> int
  end

(** The comment for module Foo *)
module Foo =
  struct
    (** The comment for x *)
    val x : int
    (** A special comment in the class, but not associated to any element. *)
  end

(** The comment for module type my_module_type. *)
module type my_module_type =
  sig
    (* Comment for value x. *)
    val x : int
    (* ... *)
  end

15.2.2 The Stop special comment

The special comment (**/**) tells OCamldoc to discard elements placed after this comment, up to the end of the current class, class type, module or module type, or up to the next stop comment. For instance:

class type foo =
  object
    (** comment for method m *)
    method m : string

    (**/**)

    (** This method won't appear in the documentation *)
    method bar : int
  end

(** This value appears in the documentation, since the Stop special comment
    in the class does not affect the parent module of the class.*)
val foo : string

(**/**)
(** The value bar does not appear in the documentation.*)
val bar : string
(**/**)

(** The type t appears since in the documentation since the previous stop comment
toggled off the "no documentation mode". *)
type t = string

The -no-stop option to ocamldoc causes the Stop special comments to be ignored.

15.2.3 Syntax of documentation comments

The inside of documentation comments (**...*) consists of free-form text with optional formatting annotations, followed by optional tags giving more specific information about parameters, version, authors, ... The tags are distinguished by a leading @ character. Thus, a documentation comment has the following shape:

(** The comment begins with a description, which is text formatted
   according to the rules described in the next section.
   The description continues until the first non-escaped '@' character.
   @author Mr Smith
   @param x description for parameter x
*)

Some elements support only a subset of all @-tags. Tags that are not relevant to the documented element are simply ignored. For instance, all tags are ignored when documenting type constructors, record fields, and class inheritance clauses. Similarly, a @param tag on a class instance variable is ignored.

At last, (**) is the empty documentation comment.

15.2.4 Text formatting

Here is the BNF grammar for the simple markup language used to format text descriptions.

text ::= (text_element)+
text_element ::=
| {[0-9]+ text} format text as a section header; the integer following { indicates the sectioning level.
| {[0-9]+:label text} same, but also associate the name label to the current point. This point can be referenced by its fully-qualified label in a {! command, just like any other element.
| {b text} set text in bold.
| {i text} set text in italic.
| {e text} emphasize text.
| {C text} center text.
| {L text} left align text.
| {R text} right align text.
| {ul list} build a list.
| {ol list} build an enumerated list.
| {{:string}text} put a link to the given address (given as a string) on the given text.
| [string] set the given string in source code style. | {[string]} set the given string in preformatted source code style.
| {v string v} set the given string in verbatim style.
| {% string %} take the given string as raw LaTeX code.
| {!string} insert a reference to the element named string. string must be a fully qualified element name, for example Foo.Bar.t. The kind of the referenced element can be forced (useful when various elements have the same qualified name) with the following syntax: {!kind: Foo.Bar.t} where kind can be module, modtype, class, classtype, val, type, exception, attribute, method or section.
| {!modules: string string ...} insert an index table for the given module names. Used in HTML only. | {!indexlist} insert a table of links to the various indexes (types, values, modules, ...). Used in HTML only.
| {^ text} set text in superscript.
| {_ text} set text in subscript.
| escaped_string typeset the given string as is; special characters ('{', '}', '[', ']' and '@') must be escaped by a '\' | blank_line force a new line.
list ::=
| ({- text})+
| ({li text})+

A shortcut syntax exists for lists and enumerated lists:

(** Here is a {b list}
- item 1
- item 2
- item 3


The list is ended by the blank line.*)

is equivalent to:

(** Here is a {b list}
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)

The same shortcut is available for enumerated lists, using '+' instead of '-'. Note that only one list can be defined by this shortcut in nested lists.

In the description of a value, type, exception, module, module type, class or class type, the first sentence is sometimes used in indexes, or when just a part of the description is needed. The first sentence is composed of the first characters of the description, until

  • the first dot followed by a blank, or
  • the first blank line

outside of the following text formatting : {ul list}, {ol list}, [string], {[string]}, {v string v}, {% string%}, {!string}, {^ text}, {_ text}.

15.2.5 Documentation tags (@-tags)

Predefined tags

The folowing table gives the list of predefined @-tags, with their syntax and meaning.

@author string The author of the element. One author by @author tag. There may be several @author tags for the same element.
@deprecated text The text should describe when the element was deprecated, what to use as a replacement, and possibly the reason for deprecation.
@param id text Associate the given description (text) to the given parameter name id. This tag is used for functions, methods, classes and functors.
@raise Exc text Explain that the element may raise the exception Exc.
@return text Describe the return value and its possible values. This tag is used for functions and methods.
@see <url> Add a reference to the URL between '<' and '>' with the given text as comment.
@see 'filename' text Add a reference to the given file name (written between single quotes), with the given text as comment.
@see "document name" text Add a reference to the given document name (written between double quotes), with the given text as comment.
@since string Indicates when the element was introduced.
@version string The version number for the element.

Custom tags

You can use custom tags in the documentation comments, but they will have no effect if the generator used does not handle them. To use a custom tag, for example foo, just put @foo with some text in your comment, as in:

(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)

To handle custom tags, you need to define a custom generator, as explained in section 15.3.2.