On Thu, Jan 15, 2009 at 10:46 AM, Ross Mellgren
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