[MLton] SML documentation tool(s)
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.