[MLton] SML documentation tool(s)

[Matthew Fluet]

> 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. 

To an extent.  There are tools (in the ML-Doc suite) for extracting
signatures from the SGML doc files.  So, ideally, when the interface
changes, you edit the ML-Doc source, updating both the documentation and
the interface types, finally deriving the signatures.

This works somewhat less well for the implementation of an interface, but 
I find that that isn't as problematic, as many implementations warrant 
documentation along the lines of

  structure Foo implements signature FOO

which isn't all that hard to maintain as you improve upon structure Foo;
all the "real" information is in the description of the signature FOO.

ML-Doc, as best I can tell, is all about documenting the interface, and
not the implementation.  And this has signficicant advantages -- you can
order the documentation in a manner that fits the interface, not the
implementation.  For example, almost every list processing function is
written in terms of "fold{l,r}".  Hence, these functions must appear
textually before other functions.  But that means I can't present "app",
"filter", "all", "exists" in the documentation before "fold{l,r}".
Whereas, when I document the inteface, I can present the functions in 
whatever order is naturally (say, alphabetically).

> 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).

Even if there is a single implementation, it should have a well defined 
interface.  In languages like Java, where there is little to no separation 
between implementation and interface, it is expedient to embed 
documentation in the implementation.

> So, I would like to know whether others strongly prefer to keep documentation
> separate from the source code or not. 

I don't strongly prefer one over the other, but it has been my experience 
that keeping a signature separate from its structure leads to more 
complete interfaces.  Looking at the signature in isolation, I tend to see 
obvious holes, even if I don't have immediate need for that functionality.  
When I just write a structure unconstrained by a signature, I'm more 
likely to throw in ad-hoc functions without much thought to the artifact 
as a whole.

> 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.)

I want to say that I've heard of another tool for SML documentation, but 
I can't recall.