Markup Differences from OCamldoc

The canonical description of the markup that odoc understands is in this section of the OCaml reference manual. The eventual aim is to support the in-code markup in its entirety, although right now there are some gaps. There are also some extensions where odoc goes beyond what is officially supported.

The example interface foo.mli described in the OCaml manual can be seen rendered by odoc here.


The following describes the changes between what odoc understands and what’s in the OCaml manual.



  1. @returns is a synonym for @return
  2. @raises is a synonym for @raise
  3. @open and @closed and @inline are hints for how 'included' signatures should be rendered
  4. @canonical allows a definition of a module, module type or type to be marked as canonically elsewhere.

Reference Syntax

odoc has a far more powerful reference resolution mechanism than OCamldoc. While it supports the mechanism in OCamldoc used for disambiguating between different types of references, it offers a more powerful alternative. The new mechanism allows for disambiguation of each part in a dotted reference rather than just the final part. For example, where the reference manual suggests the syntax {!type:Foo.Bar.t} to designate a type, and {!val:Foo.Bar.t} a value of the same name, the new odoc syntax for these comments would be {!Foo.Bar.type-t} and {!Foo.Bar.val-t}. This allows odoc to disambiguate when there are other ambiguous elements within the path. For example, we can distinguish between a type or value t within a module or module type with the same name: {!module-Foo.module-type-Bar.type-t} or {!module-type-Foo.module-Bar.val-t}.

Additionally we support extra annotations:

Referencing items containing hyphens or dots

If it is necessary to reference a reference that contains hyphens or dots - e.g. if you have a file docs-with-dashes.mld or docs.with.dots.mld, to reference them use quotation marks in the reference. For the previous two examples, the references would be {!page-"docs-with-dashes.mld"} and {!page-"docs.with.dots"}.