jon.recoil.org
this repo has no description
1{0 Markup Differences From OCamldoc}
2
3The 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}
4of the OCaml reference manual. The eventual aim is to support the in-code markup
5in its entirety, although right now there are some gaps. There are also some
6extensions where [odoc] goes beyond what is officially supported.
7
8The example interface [foo.mli] {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement}described in the OCaml manual}
9can be seen rendered by [odoc] {{!Odoc_examples.Markup.Foo}here}.
10
11{2 Changes}
12
13The following describes the changes between what [odoc] understands and what’s in the OCaml manual.
14
15- Heading levels are more restrictive. In the manual, it suggests any whole number is acceptable. In [odoc],
16 similarly to the HTML spec, we allow headings from 1-5. Heading level [0] is for the title
17 of [.mld] files. [odoc] emits a warning for heading levels outside this range and caps them.
18- Tags are restricted in scope and do not need to be put at the end of the docstring.
19
20{3 Omissions}
21- Comments describing class inheritance are not rendered ({{:https://github.com/ocaml/odoc/issues/574}GitHub issue}).
22- [odoc] handles ambiguous documentation comments as the compiler does (see {{:https://caml.inria.fr/pub/docs/manual-ocaml/doccomments.html}here})
23 rather than treating them as the OCamldoc manual suggests.
24- [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}).
25- {{: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}).
26- [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}).
27- [{!indexlist}] is not supported ({{:https://github.com/ocaml/odoc/issues/577}GitHub issue}).
28- 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}.
29 Synopses are used when rendering declarations (of modules, classes, etc.) and [{!modules:...}] lists.
30 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}).
31
32{3 Improvements}
33- [odoc] supports writing mathematics and tables with a specific syntax.
34- [odoc] supports the inclusion of medias such as audio, video and image.
35- [odoc] has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document.
36- Built-in support for standalone [.mld] files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.
37- Structured output: [odoc] can produce output in a structured directory tree rather a set of files.
38- A few extra tags are supported:
39 + [@returns] is a synonym for [@return].
40 + [@raises] is a synonym for [@raise].
41 + [@open] and [@closed] and [@inline] are hints for how 'included' signatures should be rendered.
42 + [@canonical] allows a definition of a [module], [module type], or [type] to be marked as canonically elsewhere.
43
44{2 Reference Syntax}
45[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,
46it 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,
47where 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
48comments 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
49distinguish 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}].
50
51Additionally, we support extra annotations:
52- [module-type] is a replacement for [modtype].
53- [class-type] is a replacement for [classtype].
54- [exn] is recognised as [exception].
55- [extension] refers to a type extension.
56- [extension-decl] refers to the declaration point of an extension constructor.
57- [field] is a replacement for [recfield].
58- [instance-variable] refers to instance variables.
59- [label] refers to labels introduced in anchors.
60- [page] refers to [.mld] pages as outlined above.
61- [value] is recognised as [val].
62
63Moreover, [odoc] adds support for referencing polymorphic variants in type
64aliases such as [type t = [ `A ]]. The [constructor] annotation is extended for
65polymorphic variants.
66
67{3 Referencing Items Containing Hyphens or Dots}
68
69If it is necessary to reference a reference that contains hyphens or dots (e.g., if you have a file [docs-with-dashes.mld] or
70[docs.with.dots.mld]) use quotation marks in the reference. For the previous two examples, the references
71would be [{!page-"docs-with-dashes"}] and [{!page-"docs.with.dots"}].
72