[MLton] SML documentation tool(s)

[Vesa Karvonen]

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.

> 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. For
example:

  (**
   * The first sentence of the comment is the summary sentence and is
   * displayed along with the signature name in lists (index, contents,
   * etc). The rest of the comment is displayed when the documentation of
   * the particular signature is being viewed.
   *)
  signature FOO =
    sig
      val fromBar : bar -> foo
      (** This comments applies to the above `fromBar' specification. *)
    end

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.

> 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 this doesn't apply to what I'm suggesting. The order of
val-specifications in a SML signature can be chosen freely. The order of
val-declarations in a SML structure is more constrained, but it doesn't
matter as the documentation would be along with the signature.

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

I don't think that there is fundamental difference between SML and Java
in this respect. For example, the OCaml library documentation is not that
different from JavaDoc documentation.

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

I agree.