odoc

What is odoc?

odoc is a documentation generator for OCaml. It reads doc comments from your source files and your .mld files, then outputs HTML, LaTeX and man pages. The pages you are reading now are rendered using odoc.

Text inside doc comments (delimited by (** ... *)) is marked up in odoc syntax:

val float_dsig : int -> float t
(** [float_dsig d] rounds the normalised {e decimal} significand
    of the float to the [d]th decimal fractional digit and formats
    the result with ["%g"]. Ties are rounded towards positive
    infinity. The result is NaN on infinities and only defined for
    [0 <= d <= 16].

    {b Warning.} The current implementation overflows on large [d]
    and floats. *)

These comments are picked up by odoc and turned into HTML, LaTeX, or manpages.

The syntax reference is a refinement of that explained in the OCaml manual. The differences are described here.

odoc's main advantages over OCamldoc are:

• an accurate cross-referencer that can calculate links between types, modules, module types, and more. So if you've ever been baffled by exactly what the t was in val f : A(M).t -> unit, odoc will link to it!
• an expander, which can expand complex module-type expressions while preserving their structure, including comment, includes, and more. If you've ever wondered what values there are in your module M : Base.Applicative.S with type t := u, odoc will show you!

For Library Authors

For guidance on how to document your OCaml project, see odoc for authors.

For Integrators

To integrate odoc into your tool, webpage or any other setting, you'll need to understand how to drive odoc.

Page Index

The main other pages of this site:

• odoc_for_authors gives information for odoc authors.
• cheatsheet provides a quick quide for odoc markdown.
• features explores odoc's language features.
• driver describes how odoc produces documentation.
• ocamldoc_differences outlines differences from OCamldoc.
• dune shows how to create docs using Dune.
• parent_child_spec delineates parent/child specifications.
• interface describes odoc's public-facing interface and their support guarantees.
• ocamlary demonstrates the rendering of most of the OCaml constructs.
• api_reference lists odoc's API reference library.