[ocaml-platform] codoc 0.2.0: an alpha release of a new OCaml documentation generator
dwws2 at cam.ac.uk
Tue Feb 10 14:30:33 GMT 2015
Yesterday, OCaml Labs published an alpha version of a new OCaml
documentation generator, codoc 0.2.0 <https://github.com/dsheets/codoc>.
To try it out, simply follow the directions in the README on that page.
For a sample of the current, default output of the tool, see
codoc's aim is to provide a widely useful set of tools for generating
OCaml documentation. In particular, we've strived to:
1. Cover all of OCaml's features
2. Provide accurate name resolution and linking
3. Support cross-linking between different packages
4. Expose interfaces to the components we've used to build codoc
5. Provide a magic-free command-line interface to the tool itself
6. Reduce external dependencies and default integration with other tools
We haven't yet achieved all of these at all levels of our tool stack but
we are getting close. codoc 0.2.0 is usable today (if a little rough in
some areas like default CSS).
Please keep in mind that codoc, doc-ock-lib, and doc-ock-xml are still
under heavy development and are not feature complete. Notably, there are
some important outstanding issues:
1. Class and class type documentation has no generated HTML
2. CSS is subpar (<https://github.com/dsheets/codoc/issues/22> and others)
3. codoc html does not understand --package
4. opam doc is too invasive (temporary for demonstration purposes;
tracked by <https://github.com/dsheets/codoc/issues/48>)
5. Documentation syntax errors are not reported in the correct phase or
obviously enough <https://github.com/dsheets/codoc/issues/58>
6. Character sets are not handled correctly
7. -pack and cmt extraction are not supported
8. Inclusion/substitution is not supported
The developers are very happy to take suggestions, comments, complaints,
bug reports, and patches at <https://github.com/dsheets/codoc/issues>.
We do hope that you'll let us know what you think and help us build a
next generation documentation tool which will serve our community admirably.
Keep Caml and Curry On,
More information about the Platform