[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Creighton Hogg]

On Thu, Jan 15, 2009 at 10:46 AM, Ross Mellgren <rmm-haskell at z.odi.ac> wrote:
<snip>
> Usually when encountering something like "Monoid" (if I didn't already know
> it), I'd look it up in the library docs. The problem I've had with this
> tactic is twofold:
>
> First, the docs for the typeclass usually don't give any practical examples,
> so sometimes it's hard to be sure that the "append" in "mappend" means what
> you think it means.
>
> Second is that there appears to be no way to document an _instance_. It
> would be really handy if there were even a single line under "Instances >
> Monoid ([] a)" that explained how the type class was implemented for the
> list type. As it is, if you know what a Monoid is already, it's easy to
> figure out how it would be implemented. If you don't, you're either stuck
> reading a bunch of pages on the generic math term monoid and then finally
> realizing that it means "appendable" (and other similar things), or
> grovelling through the library source code seeing how the instance is
> implemented.

I think you have a good point regarding documentation.  Usually what I
end up doing is just going into ghci & testing out the instances with
some trivial cases to make sure I have good intuition for how it's
going to work.  I don't think this a problem with the term 'monoid'
though, but just a very generic problem with documentation.  I have to
do the same thing to understand an instance of Foldable despite how
literal the name is.  I don't know if it's very practical, but I like
the idea of haddock generating either links to the source of the
instance or some kind of expandable block that will show you the
literal code.

Cheers,
Creighton