[Haskell-cafe] complete documentation like the one from Java or C++

Fergus Henderson fjh007 at galois.com
Fri Sep 10 13:48:00 EDT 2004

On 10-Sep-2004, Cale Gibbard <cgibbard at gmail.com> wrote:
> Just in case it's not what you're referring to, 
> http://www.haskell.org/ghc/docs/latest/html/libraries/index.html
> together with the Haskell report
> http://www.haskell.org/onlinereport/
> generally does the trick for me.
> Occasionally, descriptions are left out when the name of the thing
> together with the type signature generally tells you what it does.
> (e.g. things like "isEmptySet :: Set a -> Bool" are pretty obvious.)

Sometimes descriptions are left out even when it is not obvious. 
For example, the documentation for Control.Monad.Fix
merely says "The Fix monad.  Inspired by [... reference to 40-page paper
...].", and it turns out that the module is only very loosely inspired by
a few small parts of the cited paper.  The module defines a class method
"mfix" which is not documented and which does not appear to correspond
with any class method in the cited paper.   In this case, since the function
is a class method, it is crucial to document the intended contract which
users of the class method can assume and which implementors of the class
method must satisfy.  But this has not been done.

The Control.Monad.Fix module also defines a function "fix", and here
things seem a little better, since there is a function "fix" mentioned
in the paper (NOT in the paper's section on monads, but instead in a
section titled "computing with lattices").  However, the fix function in
the paper has a different type than the fix function in Control.Monad.Fix,
and because of this the two cannot possibly have the same semantics.

In the case of "fix", you can at least look at the ghc library source code.
But that doesn't work for class methods like "mfix".

Fergus J. Henderson                 |  "I have always known that the pursuit
Galois Connections, Inc.            |  of excellence is a lethal habit"
Phone: +1 503 626 6616              |     -- the last words of T. S. Garp.

More information about the Haskell-Cafe mailing list