[MLton] SML documentation tool(s)

Matthew Fluet fluet@cs.cornell.edu
Fri, 17 Jun 2005 15:52:56 -0400 (EDT)

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

I guess this is where our views fundamentally differ.  I think "library 
reference manuals" are a great idea -- but if they are a reference, then 
they ought to be slowly changing beasts.  So, any barrier that makes it 
harder for the implementor to change the interface after it has been 
released to the community at large is a good thing.