Open damiendoligez opened 7 years ago
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.
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.
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.
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
.
I may have done something wrong when I implemented https://github.com/dbuenzli/odig/issues/1 I'll have a look at this tomorrow.
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:
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
'dodoc
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.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.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).
To sum up my take on this to close the issue would be to:
Signature
module, merging doc strings at the appropriate place if they differ with those of Ocamlbuild_*
. Ocamlbuild_*.{mli,cmi,cmti}
files.
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