[Haskell-cafe] Type classes

[Andrew Coppin]

Yesterday I read the Typeclassopedia [again]. In the course of doing 
this, I discovered that several types have class instances that do 
something useful. (Indeed, some of these instances do things that I've 
written custom functions to do.)

The trouble is, when you read the documentation, it might say something like

  data Foo
  instance Monoid Foo

This tells me that Foo is an instance of Monoid. It utterly fails to 
tell me what the heck the Monoid instance actually *does*. Now, 
sometimes it's quite obvious. (E.g., just about the only binary 
operation on lists is (++).) But sometimes it's not less obvious, and 
sometimes it's so utterly mystifying that just about the only way to 
find the answer is to either read the source code or run example code 
and try to deduce some kind of pattern in the answers.

In summary, I think we need to devise a way of better-documenting class 
instances. Sometimes important functionallity can only be accessed using 
a class, and if it isn't too obvious what a particular class instance 
does, you can miss that functionallity and end up implementing it again 
by hand. (Or worse, thinking it's just impossible.) And there's also 
little quirks like the way Eq usually means value-equality, but for 
mutable structures it's usually defined as reference-equality. And then 
of course there are non-standard user-defined classes and their instances...