Understandably, odoc focuses on generating documentation for interfaces, but as far as I’m aware, there isn’t existing support lurking in the ecosystem for generating usage documentation that is actually tied implementations in some way. If the usage docs are generated from the implementation code, the docs wont get out of sync with the library, and cut out need for pasting test cases into .mld code blocks etc, which is easy enough to forget to do.
I haven’t spent enough time digesting the way odoc is organized to figure out how easy it would be extended to do this, but at the moment I’ve been trying out a hacky solution that works directly on executable .ml source as part of a dune build. For example:
ex.ml
(** {0 Title} *)
(** blah blah blah *)
let foo = ()
(** blah blah *)
let bar = ()
let baz = ()
ex.mld
{0 Title}
blah blah blah
{[
let foo = ()
]}
blah blah
{[
let bar = ()
let baz = ()
]}
Obviously, this isn’t exactly as robust as working from compilation artifacts, and I rely on other parts of the build compiling the sources in question to know that they work, but it does the trick, taking a doc commented executable implementation to a usage demonstration html with the help of odoc and dune. Other examples (some still WIP) are linked here.
Currently, dunes documentation stanza can only be pointed at .mld files in the same directory (feature request), so as a workaround I build the alias that generates the doc subdirectory before @doc (thanks to watch mode with dune build -w @examples @doc this isn’t too painful).
Anyway I thought I’d post this to get feedback and get a sense of whether people think this is a direction worth pursuing (with odoc or otherwise). I understand that not all libraries call out for these kinds of documented usage examples, but for those that do, it’d be pretty nice. Also, thanks to @dbuenzli for starting me down on this road of trying to write better docs, reading through Vg and seeing images along with rest made me realize I needed to think a bit bigger.