OCaml Documentation Open Thread

Ecosystem
138

We even have better than that.

We have the ocamldoc language. It allows to have your documentation exactly where it is needed, in mli files, and will carry itself if you move your sources around.

The ocamldoc language is a fully featured document markup language with sectioning and checked cross references to sections and API entry points.

Doing manuals and tutorial inside .mli always felt a bit cumbersome but is entirely doable as can be witnessed in many of my packages (see this one for example). The good news is that nowadays we will gradually be able to write those larger pieces in seperate .mld files. Code sample extraction is not there yet but I hope we can have a simple design implemented soon rather than having these discussions.

The other good news is that as a programmer, the effort you need to provide in order to make the documentation you write in this language available to end-users is this: approaching zero:

  • If you are using topkg or dune-release (assuming they didn’t kill that workflow), publishing your docs online on github is a topkg distrib && topkg publish doc away.

  • Distributing this documentation with your package releases is also automatically done if you use topkg+ocamlbuild or dune: these systems compile and install the right files which odig can then pickup in order to generate cross-referenced documentation for all the packages that are installed in your opam switch and allows you to peacefully read all this wondefully produced documentation offline with the stylesheet that suits you.

One might complain that the ocamldoc language syntax is none of these alternative document markup languages whose popularity or existence came after ocamldoc’s birth but if you ever tried to write a polymorphic variant in a markdown code span you will be glad that ocamldoc’s language isn’t that one.

I understand the ocamldoc language is one more thing to learn as a newcomer but it’s not hugely complex, it’s there, it works with the advantages highlighted above and an aspiring OCaml working programmer shall meet it quite soon anyways since there are thousands of lines of documentation in hundreds of projects that are using it.

3 Likes