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.
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.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).{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).{!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).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..mld files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.odoc can produce output in a structured directory tree rather a set of files.@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.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.
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"}.