It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something...
I certainly don't disagree with you! I was just commenting on the tendency of the community to document things in academic papers. But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries. After many hours tying my brain in knots, I *think* I need to use a
monad transformer... but I've never ever done that before. So I'd like to learn how it works.
Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html. I found that paper very clear and helpful in learning to use monad transformers. Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers. -Brent