On Thu, Jan 15, 2009 at 10:46 AM, Ross Mellgren <rmm-hask...@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 _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
