{0:top [odoc] for authors}

This manual describes the features that are available and recommended for users
to write great documentation using [odoc]. See also the page listing the
{{!page-features}language features} [odoc] understands.

+ {{!getting_started}Getting started}
+ {{:#interfaces} Documenting your interfaces}
+ {{:#doc-pages} Writing documentation pages}

{1:getting_started Getting started}

To generate documentation for your project, you will almost always be using
odoc indirectly rather than executing it yourself. There are currently several
'drivers' of odoc at time of writing, each with their own strengths and
weaknesses:

- {{:https://dune.build/}Dune} is the best way to view docs while you're
  developing your project. We have a {{!page-dune}page} describing
  how to use it, but the short version is:
{v
$ dune build @doc
v}
  and the results can be found here: [_build/default/_doc/_html/index.html]
- {{:https://erratique.ch/software/odig}Odig} is the best way to view docs
  of your installed packages. After installing, try:
{v
$ odig doc odig
v}
- {{!page-driver}The reference driver} is the simplest driver, useful if you
  want to see how to integrate it with your own projects.
- {{:https://github.com/ocaml-doc/voodoo}Voodoo} is the driver used to create
  the docs for {{:https://v3.ocaml.org/packages}the new OCaml website}.

{1:interfaces Documenting your interfaces}

Odoc is built to produce documentation for your {e libraries}, and the unit of
organisation is the {e module}. Documentation is written by putting
{{!special_comments}special comments} into the source of the {e module interface} or
less commonly your {e module implementation}. 

For the HTML output, [odoc] will produce one page for each module, module type,
class and class type. This includes any submodules, so if a module [A] contains
module [B] then two HTML pages will be created, and [A/index.html] will have a
link to [A/B/index.html] at the point that module [B] is defined. So each
module, module type, class and class type should be documented keeping in mind
that it will end up as a single page with a table of contents. 

For each module, [odoc] will describe all of the values, types, module types,
classes, modules and all other elements found in module signatures, documenting
the details relevant to the OCaml type system along with any documentation
written in specially formatted comments in the source code. For any element that
references any other, for example a [value] that has a [type], [odoc] will
create links such that clicking them will link to the definitions.

The job of the library author is therefore to organise the module interface
in a logical manner and write comments explaining each type, value, exception,
type constructor and everything else. The comments are written in a rich markup
language that allows the usual formatting constructs: bold, italic, sub- and
super-script, lists, verbatim and code sections, along with section headings, 
a very rich cross-referencing mechanism and tags to add specific information 
to individual elements.

All of the OCamldoc documentation comments described in {{:https://ocaml.org/manual/ocamldoc.html#s:ocamldoc-comments}the OCaml manual}
are supported, with a few important {{!page-ocamldoc_differences}differences}. In addition, 
it is intended that all features of the OCaml language are supported by [odoc].
For examples of how the language features are handled, see the
{{!page-features}Features} page.

{2:special_comments Special Comments}

Comments containing documentation are known as {e special comments}. 
They are like normal comments except they have precisely
two asterisks at the start:

{[
(* Normal comment *)
(** Special comment containing documentation *)
(*** Normal comment *)
]}

From here on in 'comment' will refer to the special comments.
Most comments will be associated with particular elements, and this requires
the comment to be immediately before or after an element with no blank lines
in between (although non-special comments are allowed). Comments that
are not associated with a particular element are known as 'floating' comments.

If there is ambiguity, which can happen if there are two elements with a
comment directly in between, the comment will be associated with {e both}
elements. This is an example of where odoc differs from OCamldoc - read more
about that on the {{!page-ocamldoc_differences}OCamldoc Differences} page.

{[
type x
(** Ambiguous comment, associated with {e both} {!x} and {!y} *)
type y
]}

This behaviour, while inherited from the compiler, is unlikely to be desired
so a blank line should be inserted to make it clear to which element the comment
should be associated. Note that Dune will raise an error if there are ambiguous
comments in the source files.

The first comment of a module is special - it is associated with the module
as a whole. This is discussed in more detail in the section on
{{!page_structure}page structure}.

The OCaml manual has a helpful example of comment placement, reproduced here.
Note that there is an additional line inserted to avoid an ambiguous special
comment.

{[
(** 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. *)

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

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

(** Comment for type weather2  *)
type weather2 =
  | Rain of int  (** The comment for constructor 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 = {
  foo : int;  (** Comment for field foo *)
  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 associated to bar. *)

class cl :
  object

    (** Interesting information about cl *)
  end

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

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

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

    (** 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

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

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

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

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

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

  (** 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
  val x : int
  (** The comment for value x. *)

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

    (* ... *)
  end
end
]}

The result of [odoc] documenting this interface can be seen on the examples
page {{!Odoc_examples.Markup.Foo}here}.

There are no differences in how [odoc] handles comment placement between [.ml]
and [.mli] files, which is {{!page-ocamldoc_differences}another difference}
from OCamldoc.

{2 Basic markup}

Text within the comments can be formatted using the following markup. Firstly,
the simple typesetting markup:

- [{b text}] bold
- [{i text}] italic
- [{e text}] emphasis
- [{^ text}] superscript
- [{_ text}] subscript
 
{3:lists Lists}
Unordered lists:
{v
{ul {- item}
    {- item}
    {- item}}
v}
and ordered lists:
{v
{ol {- item 1}
    {- item 2}
    {- item 3}}
v}
There is also an abbreviated syntax for lists. The above could be written:
{v
- item
- item
- item
v}
and
{v
+ item 1
+ item 2
+ item 3
v}

{3:code_blocks Code Blocks}

There are various ways of inserting code elements in your documentation.

{4:inline_code_blocks Inline Code Blocks}

For inline, language agnostic source code style, use square brackets: [ [ ... ] ].

{[
(** Here, [f 0] is [None] *)
]}

All the other existing ways to insert code are meant to be used for code blocks,
not inline code fragments. Those will be formatted as a code block and will end
the paragraph. Attempting to use them inline will trigger a warning.

{4:ocaml_code_blocks OCaml Code Blocks}

OCaml code blocks can be written using the enclosing tags [ {[ ... ]} ].
The code inside these blocks will be properly styled as OCaml in the generated
doc.

{v
(** This how one binds a variable in OCaml:
    {[
    let x = 0
    ]}
*)
v}

{4:verbatim_blocks Verbatim Blocks}

It is possible to write language agnostic code blocks, also called verbatim
blocks using the enclosing tags [ {v ... v} ]. The content of these blocks will be
formatted as code but with no particular style applied.

{[
(** Here is some code formatted text:
    {v
    Some text
    v}
*)
]}

{3:escaping Escaping}

In most contexts, the characters [ { [ ] } @ ] all need to be escaped with a backslash.
In inline source code style, only square brackets need to be escaped. However, as a
convenience, {e matched} square brackets need not be escaped to aid in typesetting
code. For example, the following would be acceptable in a documentation comment:

{v
The list [ [1;2;3] ] needs no escaping
v}

In a code block section, the section is ended with a [ \]} ], and in a
verbatim formatted section, the section is ended with a whitespace character
followed by [ v} ]. It is not currently possible to escape this in either case.

{2 Links and References}

A link to a URL may be put into the text as follows:

{[
(** See {{: https://www.ocaml.org/ }the OCaml website} for news about OCaml *)
]}

This will render as a link to [https://www.ocaml.org/] with the text "the OCaml website" 

References are links to other elements - e.g., comments might wish to refer to 
a module or type elsewhere as follows:

{[
(** See the module {!Stdlib.Buffer} for more details *)
]}

While [odoc] supports the syntax for references used by OCamldoc, it has an
improved syntax that allows for disambiguating in the face of clashing names.
See the section {!page-features.reference_resolution} for an example of this.

The supported methods for referring to elements are:

- Bare: [ {!Foo.bar} ] - this works well if there are no ambiguities in what's being referred to.
- OCamldoc: [ {!type:Foo.bar} ] - here the [type] prefix applies to the last element - i.e., [bar].
This is useful if there are several identifiers [bar] in module [Foo], e.g., a type and a value.
- [odoc]: [ {!module-Foo.type-bar} ] - each element in the path may be prefixed by its type. This is
useful if there are ambiguous elements in any part of the path, e.g. in this case perhaps there is a
module type [Foo].

The prefixes supported are:
- [module]
- [module-type] (also [modtype])
- [class]
- [class-type] (also [classtype])
- [value] (also [val])
- [type]
- [exn] (also [exception])
- [method]
- [constructor] (also [const])
- [extension]
- [field] (also [recfield])
- [instance-variable]
- [label] (also [section] - for referring to headings)
- [page] (for referring to [.mld] pages)

In some cases the element being referenced might have a hyphen, a dot or a space in the name,
e.g. if trying to refer to a page from a [.mld] file "1.2.3.mld". In this case, the
element name should be quoted with double quote marks:

{v
{!page-"1.2.3"}
v}


{4 Module lists}

[odoc] supports a special reference type for referring to a list of modules.
The markup is:

{v
{!modules: A B C}
v}

This will generate a list of links to these modules. If the module has a synopsis
(see {{!synopsis}later}), this will be inserted into the list.

{3 Reference Scope}

[odoc] uses the same scoping as OCaml when resolving references,
but with one major difference. In a particular
signature, {e all} elements are in scope, even those later in the signature.
Consider the following example:

{[
(** In this floating comment I can refer to type {!t} and value {!v}
    declared later in the signature *)

type t

val v : t
]}

Elements from parent modules are also in scope in child modules. Therefore
the following will also work:

{[
val x : int
val y : int

module A : sig
  (** In this module I can refer to val {!x} declared above as well as
      type {!u} declared later in the parent module. Elements declared
      in this signature take priority, so {!y} refers to {!A.y} as
      opposed to the [y] declared in the parent signature.  *)

  val y : string
end

type u
]}

The above example can be seen rendered in the module {!Odoc_examples.Markup.Scope}.

[odoc] allows modules to be 'opened' for the purposes of resolving references.
By default, the module [Stdlib] is 'opened', allowing references like [{!List.t}]
to work. This feature is enabled via the command-line flag '--open'. Currently
inline [open] statements do {e not} bring other elements into scope.

In order for [odoc] to resolve links to other compilation units or [.mld] pages,
the referenced
unit or page must be {e compiled} and available to [odoc]. That is, when performing the
[odoc link] command, one of the include paths passed via the command-line argument
[-I] must contain the relevant [.odoc] file. This is normally the responsibility of
the {{!page-driver}driver}.

{2 Tags}

Tags are used to provide specific information for individual elements, such
as author, version, parameters, etc. Tags start with an [@] symbol, appear
at the end of documentation comments, and are not allowed elsewhere.
They should appear on their own lines, with nothing but whitespace before them.

There are three types of tag: those with no associated data (simple tags),
those with a single line of text (line tags) and those with a block of
marked-up text (block tags).

{3 Simple Tags}

The three tags with no data are hints to the HTML renderer to do with [include]s.
These are:

- [@open] - the contents of the include will be expanded by default in the HTML.
- [@closed] - the contents of the include will be collapsed by default in the HTML.
- [@inline] - the contents of the include will be rendered as if they were part of 
the signature.

{3 Line Tags}

These tags have a single line of data associated with them, [string] in the
examples below. They are:

- [@author string] - allows the author of the element to be specified.
- [@since string] - declares from which version the element has been available.
- [@version string] - declares the version of the element itself.
- [@canonical string] - declares the path to the canonical instance of this element.
Can be applied to modules, module types and types. See the {{!page-Features.canonical}
Language Features} page for more details.

The content of the tag is then the rest of the line, and it is uninterpreted,
i.e., there shouldn't be any odoc markup.

{3 Block Tags}

These tags have a block of potentially marked-up text associated with them,
and occasionally some more data too. The block of text is ended by the end
of the comment or by another tag. They are:

- [@deprecated text] - marks the element as deprecated. [text] should describe
when the element was deprecated, what to use as a replacement, and possibly
the reason for the deprecation
- [@param id text] - Associate the the given description (text) to the given 
parameter name id. OCamldoc uses this tag for functions, methods, classes 
and functors, but [odoc] does not currently enforce this restriction.
- [@raise exn text] - Indicates that the element may raise [exn]. The text should
describe when this might occur. [@raises] is a synonym for this tag.
- [@return text] - describes the return value. [@returns] is a synonym for this.
- [@before version text] - Allows differences in past behaviour to be described.
This is intended to be used to document compatibility issues.
- [@see < URL > text] - Add a reference to the URL with [text] as a comment.
- [@see 'filename' text] - Add a reference to the given file (written between
single quotes), with the given text as comment. {e Note:} [odoc] currently
doesn't turn this into a link in the output HTML.
- [@see "document-name" text] - Adds a reference to the given document name
(written between double quotes), with the given text as comment. {e Note:} 
As with the file reference, [odoc] doesn't turn this into a link.

{2 Stop Comments}

The special comment:

{v
(**/**)
v}

is a {e stop comment}. It acts as a toggle, causing subsequent elements to be
omitted from the documentation. If the stop comment is repeated the subsequent
items will be visible once more.

The OCaml manual provides an instructive example:

{[
  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 output of this as rendered by [odoc] is {{!Odoc_examples.Markup.Stop}here}.


{1:page_structure Page Structure}

Producing good documentation for your library is more than simply annotating
the various modules, type and functions that are contained however. 
[odoc] expects the documentation to be structured in a logical way, and will work
best if the following conventions are applied.

The overall structure is that modules start with a {{!preamble} preamble} or
'Lead Section' that serves as an overview of the most important information
about the module. This is followed by the content of the module, organised into {e
sections} and {e subsections}, the structure of which will be used to populate
a {e table of contents} which will be placed in the HTML immediately
after the preamble, and rendered by default as a sidebar.

The first paragraph of the preamble will be treated as the module {{!synopsis}
synopsis}, and will be used as a short description of the module when it
appears in a list of modules elsewhere in the documentation of the library.

{2:top_comment Top-comment}

The top-comment is the first element of a signature, if it is a documentation
comment. For example, in an [.mli] file:

{[
(** This is the top-comment of the current module. *)

module M : sig
  (** This is the top-comment of [M]. *)

    (* ... *)
  end
]}

As an exception, [open] statements and attributes are allowed to be placed before the top-comment.
For example:

{[
[@@@ocaml.warning "-6"]

(* Copyright header *)

open Base

(** This is the top-comment *)

(* ... *)
]}

Note that the top-comment can't be attached to a declaration, for example:

{[
(** This is {e not} the top-comment because it's attached to [t]. *)
type t
]}

{2 Preamble}

The preamble is composed of the comment attached to a declaration and the
top-comment of the corresponding signature, if there is one.
It is special only because it will be placed in the [header] part of the page,
just before the table of contents (if any), and is used to compute the {e synopsis}.

{[
(** This is the comment attached to the declaration. This paragraph will be the
    first of the preamble. *)
module M : sig
  (** This is the top-comment of the expansion. This paragraph will be the
      second of the preamble. *)

  (* ... *)
end
]}

The preamble stops at the first heading, the rest is moved into the [content]
part of the page. For example, the next two snippets will {e render} the same
way:

{[
module M : sig
  (** Preamble.

      {1 Heading}

      This paragraph is not part of the preamble. *)
end
]}

{[
module M : sig
  (** Preamble. *)

  (** {1 Heading}

      This paragraph is not part of the preamble. *)
end
]}

Note: A comment attached to a declaration shouldn't contain any heading.

{2:synopsis Synopsis}

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 in [{!modules:...}] lists and after {{!page-features.expansion_aliases}expanded aliases}.

Note that the synopsis is computed on top of the {e preamble}, in these two
examples, the synopsis is the same:

{[
(** This paragraph is the synopsis of the module [M].

    This paragraph is no longer the synopsis and won't be rendered in the
    current page near the declaration of [M]. This paragraph will be part of
    [M]'s preamble. *)
module M : sig
  (* ... *)
end
]}

{[
module M : sig
  (** This paragraph is the synopsis of the module [M]. *)

  (* ... *)
end
]}

{1:sections Sections and Headings}

Both API references and documentation pages can be split into sections that can
be introduced with level-1 headings. Each section can also have subsections
(level-2) and subsubsections (level-3).

Additionally paragraphs can be annotated with level-4 or level-5 headings.
Note that paragraph headings are {e not} be included in the generated table of
contents and thus should be used to introduce examples, comments or other
complementary notes. An alternative would be to consider splitting into
multiple files.

The syntax for declaring sections is as follows:

{v
{[0-6] text}
v}
or
{v
{[0-6]:label text}
v}
where the number represents the sectioning level. [0] is reserved for page titles
for [.mld] files. [label] is an optional label for the section, allowing it to be
referenced via the [{!label-...}] reference. For example:

{v
{2:foobar Foo Bar}
...
See {!label-foobar} for details
v}

In this case the reference text would be "Foo Bar" so the paragraph would read
"See Foo Bar for details".

Sections with a label cannot be referenced via the section title, only
using the label.

Note that label names can contain [-] but if they do, you have to quote the label
name in the reference link as follows:

{v
{2:foo-bar Foo Bar}
...
See {!label-"foo-bar"} for details
v}

You can use [_] instead of [-] to avoid this syntax.

Sections can also be cross referenced from another page.
If you define the following section in a [a.mld] file:

{v
{1:foo Foo}
v}

And then want to reference it from another [b.mld] page,
you can use the following syntax:

{v
See {!page-a.foo} for details
v}

{1:doc-pages Writing Documentation Pages}

Files with the [.mld] extension are called {e documentation pages} and should
be used to complement API references with tutorials or guides. They are
particularly suitable for OCaml and Reason because cross-references to
definitions, both in the current package and for external packages, are
supported.

{2 Markup}

The format of these [.mld] files is simply text that should be marked-up with
the usual [odoc] markup as described in this page. A documentation page can be seen
as a single regular docstring in a separate file.

{2 Page Title}

When defining a documentation page make sure to supply a page title as one is
not generated by default (unlike for API reference documents where the module
or module type name is used). The level-0 heading must be used for that
purpose. For example:

{[
{0 My page}
...
]}

Only one title is allowed per page, the following heading levels should be in
the range from 1 to 5 (inclusive). Don't worry, [odoc] will generate a warning
if you forget accidentally include multiple titles.

{2 Usage}

The recommended way to setup documentation pages for your project is by using
the Dune build system. It will automatically find and generate HTML for all
[mld] files in your project. See
{{:https://dune.readthedocs.io/en/latest/documentation.html#documentation-stanza}
Dune's configuration instructions} for more details.

{2 Referencing Pages}

Currently the generated HTML pages are not be automatically referenced in the
index page, you must manually add links to point to the pages in your document.

For example, if you have a page called [my_page.mld], you can create a
link to it with [{{!page-my_page}My page}] in your [index.mld] or
anywhere else in your documentation.