Hi, I would like to improve the API documentation of the Mirage (and xapi-project) libraries, to make them quicker and easier to understand. Currently I see the following problems:
- some libraries don't have good ocamldoc in .mli files (I'm guilty of this) - we don't often generate the ocamldoc and publish it anywhere - when the API changes, we don't publish the previous versions or highlight the differences - we don't often create tutorial content to complement the API reference I'd like to gather together ideas for improvement and links to examples of good API documentation, which we could try to emulate. Regarding ocamldoc content, I think libraries like Daniel Bünzli's (cc:d) cmdliner[0] show how nice it can be. I also notice that the examples given in the docs are also in the tests/ directory i.e. the same code was written both to test the library and document it -- this seems quite efficient. As another example Simon Beaumont (cc:d) pointed me at his ocaml-pci library[1] which rebuilds the ocamldoc from travis and auto-uploads to github pages[2]-- is this the kind of thing we should attempt to standardise, say by adding support for it into the common boilerplate ocaml-travisci-skeleton scripts? Perhaps we should embed the version in the URL so we could publish multiple versions simultaneously? I'm also a big fan of the iocamljs notebooks (e.g. the coolest notebook ever[3]). It would be really nice to write tutorials for each library to complement the API reference. Perhaps the notebooks should also be regenerated by the CI? Thoughts and suggestions welcome, -- Dave Scott [0] http://erratique.ch/software/cmdliner/doc/Cmdliner [1] https://github.com/simonjbeaumont/ocaml-pci [2] https://github.com/simonjbeaumont/ocaml-pci/blob/master/.docgen.sh [3] https://andrewray.github.io/iocamljs/oh261.html#
_______________________________________________ MirageOS-devel mailing list [email protected] http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel
