odoc interface guarantees

odoc has several 'public facing' parts with varying levels of support guarantees. This document describes what those interfaces are, what the support levels are now, and what we aim for in the future.

Documentation Comments

The first and most important is the syntax of the documentation comments present in source code. This is relevant to everyone who is writing code that’s intended to be documented by odoc, so it applies to the widest set of people. We have a separate page describing the markup differences from OCamldoc.

CLI Interface

The way in which the odoc CLI is invoked is not trivial, and it requires careful ordering and correct arguments to produce correctly linked documentation. It’s not expected that end-users will invoke odoc by hand, but rather it will be driven by separate tools. As a consequence, it’s important to preserve the tools’ ability to create good documentation with each release of odoc, so we’ll ensure backward compatibility of the CLI as much as possible. There are currently three ‘first class’ tools that 'drive' odoc. We will not make releases of odoc whilst knowingly breaking these tools. These are:

• Odig
• Dune
• OCaml

Here, OCaml refers to the newly merged configure option (from 4.12.0) that builds the standard library documentation with odoc. If the recommended way of invoking odoc changes, we will work with the maintainers of these projects to ensure they are updated correspondingly.

Additionally, there will be a reference implementation of a tool to build odoc's documentation, which should serve as a guide for anyone building other 'drivers' of odoc.

Output Formats

odoc currently outputs HTML files, man pages, and LaTex documents. In a similar vein to the CLI interface, we will try to ensure that the three tools described above will not be broken by any changes to the outputs. That is, they will succeed and produce ‘correct’ documentation. Although, we don’t make any guarantees about the internal structure of the output documents; e.g., the exact nesting of tags or sequence of LaTex commands may not be preserved. We will attempt to ensure that the HTML anchors are preserved, implying that the filenames will also be preserved.

Libraries

odoc's libraries are not currently intended to be used by other projects. There are no guarantees about the stability of the API.

Intermediate Files

The intermediate files that odoc produces (.odoc and .odocl) should be considered to be internal only and tied to the specific version of odoc.