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.

Changes

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

• Heading levels are more restrictive. In the manual, it suggests any whole number is acceptable. In odoc, similarly to the HTML spec, we allow headings from 1-5. Heading level 0 is for the title of .mld files. odoc emits a warning for heading levels outside this range and caps them.
• Tags are restricted in scope and do not need to be put at the end of the docstring.

Omissions

• Comments describing class inheritance are not rendered (GitHub issue).
• odoc handles ambiguous documentation comments as the compiler does (see here) rather than treating them as the OCamldoc manual suggests.
• odoc doesn’t ignore tags that don't make sense (e.g., @param tags on instance variables are rendered) (GitHub issue).
• Alignment elements are not handled ({C text}, {L text}, and {R text}) (GitHub issue).
• odoc does not recognise HTML tags embedded in comments (GitHub issue).
• {!indexlist} is not supported (GitHub issue).
• The first paragraph is used for synopses instead of the first sentence. Synopses are used when rendering declarations (of modules, classes, etc.) and {!modules:...} lists. Another difference is that documentation starting with a heading or something that is not a paragraph won't have a synopsis (GitHub issue).

Improvements

• odoc supports writing mathematics and tables with a specific syntax.
• odoc supports the inclusion of medias such as audio, video and image.
• odoc has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document.
• Built-in support for standalone .mld files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.
• Structured output: odoc can produce output in a structured directory tree rather a set of files.
• A few extra tags are supported:

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:

• module-type is a replacement for modtype.
• class-type is a replacement for classtype.
• exn is recognised as exception.
• extension refers to a type extension.
• extension-decl refers to the declaration point of an extension constructor.
• field is a replacement for recfield.
• instance-variable refers to instance variables.
• label refers to labels introduced in anchors.
• page refers to .mld pages as outlined above.
• value is recognised as val.

Moreover, odoc adds support for referencing polymorphic variants in type aliases such as type t = [ `A ]. The constructor annotation is extended for polymorphic variants.

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) use quotation marks in the reference. For the previous two examples, the references would be {!page-"docs-with-dashes"} and {!page-"docs.with.dots"}.