[MLton-user] Re: Extended Basis Library: proposed addition to OPTION/Option

[Vesa Karvonen]

Quoting Geoffrey Alan Washburn <geoffw at cis.upenn.edu>:
[...]
> +   fun collate cmp = fn (NONE, NONE)       => EQUAL
> +                      | (SOME _, NONE)     => GREATER
> +                      | (NONE, SOME _)     => LESS
> +                      | (SOME x1, SOME x2) => cmp (x1, x2)

Looks good.

> +   val collate : 'a Cmp.t -> 'a t Cmp.t
> +   (** Returns {EQUAL} if given {(NONE,NONE)}; {GREATER} if given {(SOME _, NONE)};
> +       {LESS} if given {(NONE, SOME _)}; for {(SOME _, SOME _)} it uses the provided
> +       comparison function. *)

I've used the following conventions while formatting documentation
comments:
- Soft line break at column 75 (74 characters per line) and hard break
  at 81 (used with discretion, e.g. when comment fits on one line).
- Start comment with an extra asterisk (**.
- Prefix each subsequent comment line with an asterisk *.
- Text on the first line only when the comment fits on one line.
- Inline code is inside curly braces {}.  A line of code starts
  with a *>.
- Comments may contain (sub)section titles:
    = Level 1 Title =
    == Level 2 Title ==
    ...
- Links in code are inside brackets [] possibly with link text, e.g.
  [http://foo bar].
I plan to write a simple utility that generates browsable documentation
from the documentation comments.

In my experience, (re)formatting comments is something that one can
do quickly.  Thinking about what to write takes time.  Although I've
experimented with slight formatting variations and might reformat
all comments at some point, I'd prefer that, for now, all comments
would follow the same formatting conventions.

I think that the content of the comment on collate is fine.  I've
personally tried to somewhat mimic the style of the Basis library
specification in documentation comments, but this isn't a requirement.
Also, I prefer to express semantics using (pseudo) code rather than
English.

Feel free to commit.  And thanks for the contribution!

-Vesa Karvonen