Markup Differences from OCamldoc

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, we follow the HTML spec in allowing headings from 1-6, and we also allow 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)
• 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. 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 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
• 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"}.