odoc_for_authors (odoc.odoc_for

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:

Dune is the best way to view docs while you're developing your project. We have a page describing how to use it, but the short version is:
```
$ dune build @doc
```
and the results can be found here: _build/default/_doc/_html/index.html
Odig is the best way to view docs of your installed packages. After installing, try:
```
$ odig doc odig
```
The reference driver is the simplest driver, useful if you want to see how to integrate it with your own projects.
Voodoo is the driver used to create the docs for the OCaml website.

Documenting your interfaces

Odoc is built to produce documentation for your libraries, and the unit of organisation is the module. Documentation is written by putting special comments into the source of the module interface or less commonly your 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 the OCaml manual are supported, with a few important 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 Features page.

Special Comments

Comments containing documentation are known as 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 both elements. This is an example of where odoc differs from OCamldoc - read more about that on the 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.

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. *)

exception My_exception of (int -> int) * int
(* Hello, I'm a simple comment :-) *)
(** 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 here.

There are no differences in how odoc handles comment placement between .ml and .mli files, which is another difference from OCamldoc.

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

Lists

Unordered lists:

{ul {- <item>}
    {- <item>}
    {- <item>}}

and ordered lists:

{ol {- <item 1>}
    {- <item 2>}
    {- <item 3>}}

There is also an abbreviated syntax for lists. The above could be written:

- <item>
- <item>
- <item>

and

+ <item 1>
+ <item 2>
+ <item 3>

Code Blocks

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

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.

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.

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

Language Headers

As of odoc.2.2 it is possible to write blocks with explicit language headers. These blocks can be written using the enclosing tags {@<language>[ ... ]}. The content of those block should be properly styled if highlightjs supports the styling for the given language.

(** Here is some python code:
    {@python[
    def f():
      return 0
    ]}
*)

And rendered this becomes:

Here is some python code:

def f():
  return 0

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}
*)

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, matched square brackets need not be escaped to aid in typesetting code. For example, the following would be acceptable in a documentation comment:

The list [ [1;2;3] ] needs no escaping

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.

Links and References

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

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

This will render as a link to https://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 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 (and the equivalent deprecated prefix modtype)
class
class-type (and the equivalent deprecated prefix classtype)
val (and the equivalent deprecated prefix value)
type
exception (and the equivalent deprecated prefix exn)
method
constructor (and the equivalent deprecated prefix const)
extension
extension-decl for refering to the declaration point of an extension constructor
field (and the equivalent deprecated prefix recfield)
instance-variable
section (and the equivalent deprecated prefix label) - 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:

{!page-"1.2.3"}

Module lists

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

{!modules: A B C}

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

Reference Scope

odoc uses the same scoping as OCaml when resolving references, but with one major difference. In a particular signature, 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 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 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 driver.

Mathematics

Odoc 2.2 introduced new markup for maths, available both for inline and block content. The syntax for the maths itself is LaTeX and it is rendered by KaTeX in HTML output, dropped inline in the LaTeX output, and ignored in the man-page renderer.

To render maths inline, use {m <latex>} and for block mode use {math <latex>}.

This is an inline equation: $x=\frac{-b \pm \sqrt{b^2-4ac}}{2a}$ , and rendered in block form this becomes:

x=\frac{-b \pm \sqrt{b^2-4ac}}{2a}

See the KaTeX documentation for the HTML mode LaTeX support status.

Tables

Odoc 2.3 introduced new markup for tables. This markup comes in two flavors: the light syntax, and the heavy syntax.

The heavy syntax uses several markup: {table ...} to define a table, {tr ...} to define a row, and {th ...} and {td ...} to respectively define a header cell and a data cell. Direct children of tables have to be rows, and direct children of rows have to be cells. Similarly, rows have to be direct children of tables, and cells direct children of row. Cells can contain any markup.

For instance, the following table:

{table
  {tr
    {th Header 1}
    {th Header 2}
    {th Header 3}
  }
  {tr
    {td Cell 1}
    {td Cell with {e emphasized content}}
    {td {v a block v} }
  }
}

would render as

Header 1	Header 2	Header 3
Cell 1	Cell with emphasized content	a block

The light syntax has the advantages of being simple to read, even as plain text. It is very similar to the GFM Markdown syntax, with the exception that it has to be enclosed in {t ...}, and that the inline markup is the ocamldoc one. It supports alignment for columns using the : notation, from the GFM syntax: --- is the default alignment, :-- left-aligned, --: right-aligned and :---: is centered.

The following table, in light syntax:

{t
  | Header 1 | Header 2 | Header 3 | Header 4|
  | :------: | --------:|:---------|---------|
  | centered | right    | left     | default |
    omitted  | bar at   | start and| finish
  | {e emph} | and | unaligned | bars |
}

would render as

Header 1	Header 2	Header 3	Header 4
centered	right	left	default
omitted	bar at	start and	finish
emph	and	unaligned	bars

The light syntax has the advantages of being arguably more readable for small tables, when viewing the source file directly. However, its content is restricted (for instance, no new line is allowed). The heavy syntax is easier to write, can be more readable for big tables, and supports having any kind of content inside. It does not support alignment (yet).

Stop Comments

The special comment:

(**/**)

is a 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 here.

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 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 sections and subsections, the structure of which will be used to populate a 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, 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.

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

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 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 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.

Synopsis

The synopsis of a module (a module type, a class, etc..) is the first paragraph of the Preamble, if the preamble starts with a paragraph.

It is rendered in {!modules:...} lists and after expanded aliases.

Note that the synopsis is computed on top of the 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

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 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.

Finally, documentation pages should start with a level-0 heading, see Page Title. Level-0 headings should not be used elsewhere.

The syntax for declaring sections is as follows:

{[0-5] <text>}

{[0-5]:<label> <text>}

where the number represents the sectioning level. <label> is an optional label for the section, allowing it to be referenced via the {!section-<label>} reference. For example:

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

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:

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

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:

{1:foo Foo}

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

See {!page-a.foo} for details

Writing Documentation Pages

Files with the .mld extension are called 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.

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.

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.

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 Dune's configuration instructions for more details.

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.

`odoc` for authors