[MLton] SML documentation tools

[Stephen Weeks]

It occurs to me that a powerful way to build an SML documentation
system by embedding documentation in SML comments would be to
integrate with -show-basis, so that the description of a value appears
just above its type signature.  If you could do this, you would
automatically get documentation specialized to whatever basis you
want, with all the power of SML module system to slice and dice the
documentation by building new bases. You could build a beginner
library by signature restriction, and the beginners would see only the
relevant documentation.  Or you could combine two software packages by
and get combined documentation.  etc.

Such an approach would also provide a nice cross-check on the validity
of the documentation.  Since the type signatures are automatically
generated by type inference, if the documentation doesn't agree, it is
clearly out of date.

As to implementing this, I don't think it's super hard.  One has to
do some tedious work to get the comments past the lexer and into the
elaborator.  Once the comments are there, the elaborator can probably
do some fairly straightforward "static" propagation of comments (to
handle redeclaration, signature ascription, functor application, open,
etc).  One could even combine comments on signature ascription to
automatically get the abstract spec (what the signature documentation
says) plus the dirty details (what the structure documentation says).