odoc.mld

@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver
@short_title [odoc]

{0 The [odoc] documentation generator}

{b For a quick look at the [odoc] syntax, see the {{!cheatsheet}cheatsheet}!}

{1:overview 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 {{!Fmt.float_dsig}turned into HTML}, LaTeX, or manpages.

The syntax reference is a refinement of that explained in the
{{:https://ocaml.org/manual/ocamldoc.html}OCaml manual}. The differences
are described {{!page-ocamldoc_differences}here}.

[odoc]'s main advantages over OCamldoc are:

- an accurate {e 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 {e 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!

{1 For Library Authors}

For guidance on how to document your OCaml project, see {{!page-odoc_for_authors}[odoc] for authors}.

{1 For Integrators}

To integrate [odoc] into your tool, webpage or any other
setting, you'll need to understand {{!page-driver}how to drive [odoc]}.

{1 Page Index}

The main other pages of this site:
- {!page-odoc_for_authors} gives information for [odoc] authors.
- {!page-cheatsheet} provides a quick quide for [odoc] markdown.
- {!page-features} explores [odoc]'s language features.
- {!page-driver} describes how [odoc] produces documentation.
- {!page-ocamldoc_differences} outlines differences from OCamldoc.
- {!page-dune} shows how to create docs using Dune.
- {!page-parent_child_spec} delineates parent/child specifications.
- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.