[MLton] SML documentation tool(s)

[Vesa Karvonen]

Quoting Matthew Fluet <fluet@cs.cornell.edu>:
> > > 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.

No. To me it seems like you are reading something between the lines that
isn't there. I'm not implying that one should make changes to the interface
of a library just because it is possible.

> I think "library reference manuals" are a great idea -- but if they are
> a reference, then they ought to be slowly changing beasts.

I don't think that we disagree here. In my view, the reference manual of
an established library that has a large user base should be changing
slowly. More radical changes to such a library should probably be done by
starting a completely new (incompatible) major version.

However, it often takes some time for a library to mature and it makes
little sense, in my opinion, to cast the interface of a library in
concrete too early. While a library is being designed (refined) and before
it actually has a significant external user base, it makes more sense to
adjust the interface of the library based on the experience gained by
using it. To me this is just common sense.

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

The only barrier that I think is worth having is a significant external
user base. Any artificial barriers beyond that are just there to waste
human life.