Legend:
Library
Module
Module type
Parameter
Class
Class type
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 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, and heading level 0 for the title of .mld files. odoc emits a warning for heading levels outside this range and caps them.
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)
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. An other 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 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:
@returns is a synonym for @return
@raises is a synonym for @raise
@open and @closed and @inline are hints for how 'included' signatures should be rendered
@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
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"}.