[MLton] SML documentation tool(s)

[Matthew Fluet]

> Quoting Matthew Fluet <fluet@cs.cornell.edu>:
> > [...] 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.
> 
> I see. The idea of ML-Doc is to generate (or extract) the SML signature
> files from the ML-Doc SGML files. It is not a bad idea for writing the
> specification of a standard library.
> 
> Looking at the SML/NJ library, it doesn't seem like the developers
> embraced the idea. There are many SML files (including files that contain
> signatures) in the library that have significantly more recent
> modification dates than any of the ML-Doc files. Actually, it doesn't
> surprise me at all. ML-Doc SGML is much more verbose than SML source code
> and probably much more painful to edit. I would be surprised to hear (and
> see evidence to the contrary) that SML/NJ developers generally write the
> ML-Doc files first and then generate the signature files from the ML-Doc
> documentation.

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.

> > This works somewhat less well for the implementation of an interface [...]
> > 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.
> 
> Hmm... There may be a slight misunderstanding. I'm definitely not
> suggesting that one should avoid using signatures. I'm only suggesting
> that the documentation of the signatures (and structures where approriate)
> would be embedded in the source code of the signatures as comments. 

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

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

> The main difference with ML-Doc is that the direction of generation is
> reversed. While documenting signatures, programmers would primarily edit
> (the comments in) ordinary SML source files that contain signature
> specifications. Documentation is then generated from the SML source code
> by parsing the signatures and associating the comments with appropriate
> signature elements.

Precisely the problem -- 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.