[MLton] SML documentation tool(s)

[Stephen Weeks]

I think the SML basis library is a perfect example of what's wrong
with having a library owned by a small group of people attempting to
stabilize too soon in the absence of lots of practical experience and
community input.  The basis has taken ~10 years to develop; it has
been ridiculously difficult to get even simple fixes made, and there
are lots of things missing because the development process is too
focused on perfection.  I would like to avoid these problems with our
library development by adopting the following principles:

 * welcome community input
 * avoid ownership of code
 * focus on practical needs of developers
 * breadth of libraries is more important than depth
 * allow rapid changes to interfaces, code, and documentation
 * keep tight integration of interface and documentation

I think we are different than the basis library because we want
documentation, not specifications.  The purpose of documentation is to
help someone dig into the code or to refresh their memory when
programming by looking at just the interface.  The specification is
the code itself.  I am willing to skimp on a lot of stuff that the
basis library shoots for in order to get good documentation and as
many libraries as possible.  I am not so interested in the following:

 * complete specifications (some documentation is better than none)
 * perfect specifications (you can always look at the code)
 * portability across SML implementations (too hard)
 * stable interfaces (not necessary, use a package system)

I'd like to emphasize that I think shooting for stable interfaces is a
terrible idea.  As Vesa said, it's a completely artificial goal until
one actually has a user base that cares.  And even then, supporting
stable interfaces is a problem to be solved by our library packaging
system, not by freezing interfaces in stone.  We should certainly be
able to come up with a packaging system that allows a piece of code to
require a certain version of a library, and even for different pieces
of code in the same program to use different versions of the same
library.  With MLBs it should all be a snap.

I agree with Vesa's point that the way development works in practice
is that the library is built first and then refined, with
documentation growing along the way.  So, I am becoming more inclined
toward a system based on extracting documentation from code than
extracting code from documentation.  Also, we don't want to put any
barriers in the way of developers producing code.  Sometimes people
other than the developer of a library will write documentation.  So,
requiring developers to use a format other than SML for their code
seems like a mistake.