odoc

For a quick look at the odoc syntax, see the cheatsheet!

What is odoc?

odoc is a documentation generator for OCaml. It reads doc comments from your source files and your .mld files, and 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 normalized {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, or TeX 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 Odoc For Authors
• cheatsheet The cheatsheet
• features Language Features
• driver Reference Driver
• ocamldoc_differences Differences from OCamldoc
• dune Dune
• parent_child_spec Parent/Child specification
• interface Interface guarantees
• ocamlary A demonstration of the rendering of most of the OCaml constructs
• api_reference Odoc's library API