[MLton] SML documentation tool(s)

Stephen Weeks MLton@mlton.org
Fri, 17 Jun 2005 08:02:04 -0700

I strongly prefer keeping documentation and code integrated
(notwithstanding the current MLton structure documentation).  I don't
have a strong preference as to whether we extract code from
documentation (like ML-Doc or noweb) or documentation from code (like
Javadoc).  I would start to get nervous, though, if the extraction of
code from documentation became complex, since at some point one could
start extending the language in the documentation system, which would
be bad.

For whatever we do, I would really like to see types in the
description section and alphabetical listings of values in interfaces.

I agree with Matthew's point that documenting signatures, not
structures, is the way to go.

On other thing to keep in mind is how to enable the community to
maintain the documentation.  I like having a wiki (or some easy way)
for doing this.  Perhaps CVS is enough, but it seems like it would be
useful to allow people with lesser privileges to create and edit