[MLton] SML documentation tool(s)

[Vesa Karvonen]

I must first say that I still haven't used ML-Doc, so I may be grossly
mistaken. However, if I understand correctly, then ML-Doc is intended to
be used in such a way that the documentation sources (SGML files) are
updated separately from the SML sources. Using ML-Doc to document a
library, one would first prepare a set of skeleton ML-Doc SGML files using
the mkdoc tool (part of ML-Doc) and then write the documentation into the
SGML files.

I really wouldn't want to get into a debate about this, but I don't like
the idea of keeping reference documentation separate from the source code.
I would prefer to keep reference documentation (mostly) in the original
(SML) source files, like is done by widely used documentation tools such
as JavaDoc and Doxygen as well as by some languages/environments such
as Emacs (elisp).

The main problem with separating the documentation from the source code is
that the documentation is then one step away from the source code and it
takes a lot more discipline to write and update the documentation. In my
experience, most programmers (including me) don't particularly love writing
documentation. Any extra indirection between the documentation and the
source code probably reduces the amount of up-to-date documentation by a
significant factor.

For comparison, the OCaml library documentation

  http://caml.inria.fr/pub/docs/manual-ocaml/index.html (Part IV)

is mostly extracted directly from the source code and it is much more
thoroughly documented than the SML/NJ library

  http://www.smlnj.org/doc/smlnj-lib/index.html

which is documented using ML-Doc.

Keeping documentation separate from source code is a reasonable approach
for writing the specification of a standard library that is expected to be
implemented independently by multiple vendors, but not (IMO) for typical
libraries that only have a single implementation (and are hopefully under
active maintenance).

So, I would like to know whether others strongly prefer to keep documentation
separate from the source code or not. If separation of documentation is
generally preferred, then improving ML-Doc is probably the way to go.
Otherwise it would make sense to write a tool to support embedding
documentation into source code and, as I'm unaware of existing tools (except
perhaps mkdoc) for SML, I'm willing to put time into implementing such a
tool. (It is not that I would want to spend time implementing a tool for the
fun of it. While working in other languages, I have used the existing tools.)