- Courses
- đ»Programming Languages
- đ«OCaml (WIP)
- Modules, Structure & Tooling
- Documentation Generation
On this page
Documentation Generation with odoc
Published on August 3, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
odoc reads specially formatted comments directly out of OCaml source files and turns them into browsable HTML documentation, cross-referenced and linked automatically across an entire project's modules, types, and values. Since it reads the exact same signatures already written for a project's .mli files, keeping documentation accurate mostly comes down to writing it once, right where the code it describes already lives.
Installing odoc and Preparing a Projectâ
odoc is installed like any other package:
opam install odoc
Generating documentation through Dune also requires the project's dune-project file to include a (package ...) stanza, since odoc organizes generated documentation by package â a project with no package declared has nothing for the documentation to be grouped under.
Writing Doc Commentsâ
A doc comment is an ordinary OCaml comment that begins with a double asterisk, (** ... *), placed directly before the value, type, or module it describes:
(** A fixed-capacity stack. *)
type 'a t
(** [create capacity] returns an empty stack that can hold at most
[capacity] elements. *)
val create : int -> 'a t
(** [push x s] returns a new stack with [x] added to the top of [s].
Raises [Failure] if [s] is already at capacity. *)
val push : 'a -> 'a t -> 'a t
Doc comments belong in the .mli file whenever one exists, since that's the file describing what's actually visible to anyone using the module â documenting private implementation details in the .ml file is rarely useful, since nothing outside the module can see them anyway. A useful convention worth following: write the first sentence of a doc comment as a complete, standalone summary of what the item does, since some documentation views and tooling display only that first sentence in a condensed listing, with the rest of the comment shown only once a reader clicks through for more detail.
Building and Viewing the Documentationâ
With doc comments in place, generating the actual HTML output is a single Dune command:
dune build @doc
The generated site appears under _build/default/_doc/_html/index.html, browsable by opening that file directly, or by running dune ocaml doc, a shortcut that builds the documentation and opens it directly in a browser in one step, without needing to locate the output path manually.
Markup Inside Doc Commentsâ
Doc comments support a lightweight markup language, letting documentation include more than plain prose. Section headers use a numbered brace syntax, {0 Title} for a top-level heading and {1 Subtitle} for the next level down; code spans use square brackets, as already seen with [create capacity] above; and lists use - for bullets. Cross-references to another documented item use {!Path.to.item}, which odoc turns into an actual hyperlink to that item's own documentation page:
(** Pushes a value onto the stack. See {!create} for how capacity is set. *)
val push : 'a -> 'a t -> 'a t
This cross-referencing is resolved automatically across the entire documented project â a reference to another module's type or function becomes a working link without any manual path bookkeeping, and stays correct even if the underlying file structure changes later, since it's resolved by the identifier itself rather than a hardcoded URL.
Package-Level Documentation with .mld Filesâ
Not every piece of documentation belongs to a specific module â a package often needs an overview page, a getting-started guide, or a narrative explanation that doesn't map to any single .mli. These live in separate .mld files, written in the same markup used inside doc comments, and are attached to a package with a documentation stanza:
(documentation
(files (glob_files_rec doc/* with_prefix .)))
A file named index.mld, placed in the documented directory, is treated specially: it becomes the entry page linked directly from the package's main documentation listing, making it the natural place for a short overview of what the package does and a pointer to its most important modules.
{0 My Library}
A small library for working with fixed-capacity stacks.
See {!module:Stack} for the core API.
What odoc Adds Beyond Plain Commentsâ
Because odoc has access to a project's full compiled type information, not just its raw text, generated documentation includes fully resolved type signatures for every value, direct links from documentation back to the corresponding source code, and automatic cross-referencing between every documented module in a project â including, when configured, links out to the documentation of a project's own dependencies. This is a meaningful step beyond a plain comment sitting next to a function: the documentation stays connected to the actual, current type signatures the compiler checks, rather than being a separate description that can silently drift out of sync with the code it's meant to describe.
Key Takeawaysâ
- odoc reads
(** ... *)doc comments, most usefully placed in.mlifiles, and turns them into cross-referenced HTML (or LaTeX or man page) documentation. dune build @docgenerates the documentation site under_build/default/_doc/_html;dune ocaml docbuilds and opens it in a browser in one step.- A doc comment's first sentence should stand alone as a complete summary, since some views display only that sentence in condensed listings.
{0 ...}and{1 ...}mark section headings,[...]marks inline code, and{!Path.to.item}creates an automatically resolved link to another documented item.- Narrative, non-module-specific documentation belongs in separate
.mldfiles, attached to a package with adocumentationstanza; a file namedindex.mldbecomes the package's entry page. - Because odoc works from a project's actual compiled type information, generated documentation includes fully resolved signatures and links directly back to source code, staying accurate as the underlying code changes.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Unit Testing
Next
Guided Exercise: Build a Mini Library
- Installing odoc and Preparing a Project
- Writing Doc Comments
- Building and Viewing the Documentation
- Markup Inside Doc Comments
- Package-Level Documentation with .mld Files
- What odoc Adds Beyond Plain Comments
- Key Takeaways
