[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

Creighton Hogg wchogg at gmail.com
Thu Jan 15 11:57:01 EST 2009

On Thu, Jan 15, 2009 at 10:46 AM, Ross Mellgren <rmm-haskell at z.odi.ac> wrote:
> 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.


More information about the Haskell-Cafe mailing list