ocamldoc_differences.mld

{0 Markup Differences From OCamldoc}

The canonical description of the markup that [odoc] understands is in {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#s%3Aocamldoc-comments}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] {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement}described in the OCaml manual} 
can be seen rendered by [odoc] {{!Odoc_examples.Markup.Foo}here}.

{2 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.

{3 Omissions}
- Comments describing class inheritance are not rendered ({{:https://github.com/ocaml/odoc/issues/574}GitHub issue}).
- [odoc] handles ambiguous documentation comments as the compiler does (see {{:https://caml.inria.fr/pub/docs/manual-ocaml/doccomments.html}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) ({{:https://github.com/ocaml/odoc/issues/575}GitHub issue}).
- {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-formatting}Alignment elements} are not handled ([{C text}], [{L text}], and [{R text}]) ({{:https://github.com/ocaml/odoc/issues/541}GitHub issue}).
- [odoc] does not recognise {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-html-tags}HTML tags embedded in comments} ({{:https://github.com/ocaml/odoc/issues/576}GitHub issue}).
- [{!indexlist}] is not supported ({{:https://github.com/ocaml/odoc/issues/577}GitHub issue}).
- The first paragraph is used for synopses instead of the {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-preamble}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 ({{:https://github.com/ocaml/odoc/pull/643}GitHub issue}).

{3 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:
  + [@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. 

{2 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.

{3 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"}].