MPR#5243: Improve the API documentation

[damiendoligez]

PR transferred from https://caml.inria.fr/mantis/view.php?id=5243
[original reporter: @Chris00]

Ideally, the API documentation for plugins should be more complete (basically serve as a reference how to write a plugin) and cross-referenced.
http://nicolaspouillard.fr/ocamlbuild/html/Signatures.PLUGIN.html

[dbuenzli]

FWIW I'm still referening to the mentioned page when I need to lookup ocamldoc's API.

It would be nice to make sure they look good in odig, currently they do not neither in the ocamldoc backend nor in the odoc one.

For this the cmi, cmti file and mli files of the API should be properly installed in ocamlbuild's lib dir. The details are here.

[gasche]

So the actionable content of this issue is "we should fix the rendering of .mli documentation". Once we do this, and get a public link to the API documentation somewhere (for example mirage.docs.io), I think we can close it, thanks to Christophe Troestler's .mli comments and the new manual.

[gasche]

I'm looking at this in more detail. Currently a raw ocamldoc *.mli -html produces output that is not very nice, because it merely gives a haphazard list of modules, some with documentation and some without, some intended for use by plugin writers and some not.

I think that the best thing to do for now is to only install signatures.{ml,cm,cmt}i, which corresponds rather well to the set of features that authors of ocamlbuild plugin should know about. (The correspondence is only partial given that people can break the Signatures abstraction by using Ocamlbuild_pack directly and some do it in practice, but it's a fairly good match; and trying to include more in a proper way would require sensibly more work.)

The structure of the Signatures documentation itself is not great, with a lot of boring stuff first and everything the user should in fact look at first being at the end. It would be nice to try to improve this by reordering the declarations in the module and having some more doc-reader-directed comments and forward pointers.

[gasche]

#227 installs signature.{cmi,cmti}. There is one thing I find surprising: the current Makefile is already careful to install signatures.mli, so why is the Signatures module not visible in the odig-generated documentations that @dbuenzli linked above?

P.S.: Looking further, it looks like there is, indeed, a generated documentation for the Signatures module (with the ocamldoc backend; odoc doesn't see it, which is explained by the fact that before #227 we don't install signatures.cm{,t}i). But odoc/odig seem to be making choices of which modules to show on the main documentation page that do not depend on which .mli are available; presumably the relevant modules are extracted from the .cma archives installed by the package, which do not directly mention Signatures.

[dbuenzli]

I may have done something wrong when I implemented b0-system/odig#1 I'll have a look at this tomorrow.

[dbuenzli]

Nothing wrong was done apparently. With #227 merged the Signatures interface shows up both in the ocamldoc and odoc backend with odig master. A few notes:

1. In ocamldoc the Ocamlbuild_* show up but are unlinked, they can't be since they don't have the .mli provided (only the .cmi files are installed) and ocamldoc needs the sources. This I think is a harmless bug w.r.t. the current spec of odig: with ocamldoc the mli you install define what gets documented, but I'm rather going to change the spec so that its consistent in both backends and thus there will be no bug... In other words the Ocamlbuild_*.mli files should be installed if you want these files to be ocamldoc'd
2. In odoc both the Ocamlbuild_* and Signature modules show up and are correctly linked. This is consistent with odig's spec, any cmi file is considered to be part of the package API and gets documented.
3. I don't understand why we need this Signature dance. It's better if ocamlbuild documents and exposes itself like every library does in the eco system, i.e. directly via the names you will have to use. If there are private parts that should not be used they should be either migrated to Private modules or properly labelled as such in the documentation.

[dbuenzli]

I forgot to add in 2. since the .cmi files are installed you should also install their corresponding .cmti files (odoc does best effort with cmi files but fundamentally it craves for .cmti files).

[dbuenzli]

To sum up my take on this to close the issue would be to:

1. Kill the Signature module, merging doc strings at the appropriate place if they differ with those of Ocamlbuild_*.
2. Install the Ocamlbuild_*.{mli,cmi,cmti} files.