@children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/ @short_title The odoc documentation generator

The odoc documentation generator

audio:https://choum.net/panglesd/odoc.mp3

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