Doc-comments language reference

OCamlFormat uses odoc-parser to parse doc-comments (also referred to as doc-strings), and hence it inherits the accepted language from odoc (detailed in odoc's documentation).

Here is an example showing a few useful elements:

(** Adding integers. *)

(** {1 Exception} *)

(** Raised in case of integer overflow *)
exception Int_overflow

(** {1 Function definition} *)

(** [add ~x ~y] returns [x + y] or raises an exception in case of integer overflow.
    Usage:
    {@ocaml some_metadata[
    # add ~x:1 ~y:2 ;;
    - : int = 3
    ]}

    Here is a basic diagram:
    {v
          add  ~x:1   ~y:2
                  \   /
                   (+)
                    |
                    3
    v}

    Notes:
    - {_ check} that exception {!exception:Int_overflow} is {b not raised};
    - have a look at {!module:Int}.

    @return [x + y]
    @raise Exception [Int_overflow] *)
val add: x:int (** one operand *) -> y:int (** another operand *) -> int (** result *)