[MLton] SML documentation tool(s)

[Vesa Karvonen]

Quoting Matthew Fluet <fluet@cs.cornell.edu>:
[...]
> Well, the SML/NJ Library existed long before ML-Doc existed.  Like many 
> endeavors to update an existing pile of code to a new documentation 
> standard, it falls very low on the developers' TODO list.
>
> This doesn't prove that the methodology is bad, but rather that it is 
> cumbersome to apply to an existing library.

Exactly!

Perhaps it is just me, but most libraries seem to be mostly implemented
before any documentation is written. I think that it is not difficult to
understand why this happens. For one thing, it makes no sense to document
something that isn't stable enough to be documented. When I'm designing a
library, it usually takes some time before the design stabilizes. What I
do is that I make a small scale prototype implementation of the library
and try it on small scale practical problems. I then adjust the design of
the library as I uncover practical problems in the design. This may not be
the recommended approach of the SEI, but seems to be the de facto process.
If I would start by writing the documentation, I would probably waste a
lot of time documenting things that don't end up in the library or, worse,
might end up with a nicely documented library that sucks.

The case for producing a specification for a standard library is very
different. For one thing, the reason to standardize something is that
there are so many variations (existing designs to choose from with
well known consequences) of the thing that a standard is needed for
progress. (See

  http://www.artima.com/weblogs/viewpost.jsp?thread=4840

for an elaborated discussion of this point.)

I would rather have tools that support the processes that people do use
rather than tools that force people to use a specific process that almost
nobody uses (or face the consequences of having to duplicate work).

But, like I said, I really would prefer not to need to debate this. At any
rate, anyone can choose to use the tool that best suits their process.

> Which begs the question -- why bother extracting the documentation?  why 
> not just read the source code?

Because the generated documentation can be formatted, distributed (made
available), structured and hyperlinked in ways that are difficult to
achieve with plain source code and typical programming environments or
conventional mediums (web, print).

> If documentation adds something that cannot be gleaned from the source 
> code, why perpetuate the illusion that they can be combined?

There are many forms of documentation. The form of documentation that I'm
talking about here could be called something like "library reference manual".
Fundamental to a library reference manual is that it is strongly tied to the
interface of the library. Any change in the interface is likely to mean that
a corresponding change should be made to the reference manual. In order to
keep the reference manual and the source code synchonized, it is a good idea
to keep them together.

The reason why I want the manual to be generated from the code is that the
code is likely to exist before the manual and there are practical reasons why
this will remain so despite the availability of tools whose creators believed
the contrary.

> [...] parsing SML is crappy to begin with, some 
> documentation extraction tool is going to be taking shortcuts anyways, 
> You don't want to try to do all the dependency analysis and elaboration 
> that an SML compiler is doing just to resolve what a particular type name 
> signifies.

I doubt that it makes a practical difference. A library whose signatures
are so convoluted as to require complex analysis to produce reasonable
documentation for is probably not a good library to begin with.