Re: Control.Monad.Error documentation
----- Original Message ----
From: Neil Mitchell
"Rendered by Michael Weber mailto:michael.weber@post.rwth-aachen.de, inspired by the Haskell Monad Template Library from Andy Gill (http://www.cse.ogi.edu/~andy/)";
I can see the use of linking to papers describing modules, or linking to sources of information where further details can be found, but I can't remember many other modules which just have links to the authors? If author credit is needed, wouldn't the source code be a better place to put it?
Do you suggest to move this information to the source code comments, so they won't appear in Haddock output? I'm for it. Any objections?
The bit at the top of description seems useful.
Great. I'll use same format for other monads.
The example seems awfully long.
The documentation contains 2 examples - one about general use of Error, the second one is about ErrorT monad transformer. You are right, the first example seems too long as for library documentation. Neil, you are not in general against examples in the library documentation, right? What do you think if I replace the first example with more cut-and-dry one, similiar to the ErrorT example? Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Hi
Do you suggest to move this information to the source code comments, so they won't appear in Haddock output? I'm for it. Any objections?
No idea. To give the author is kind of OK (other modules do it), but to have the guy who rendered it, but not the guy who is currently re-rendering seems like its starting to get a bit out of hand.
The bit at the top of description seems useful. Great. I'll use same format for other monads.
I know not much about Monads - the idea of having some common "what this does bit" looks handy, you'd have to get someone elses input as to whether your format captures the "right" info - although it looks fine to me :)
The example seems awfully long.
Neil, you are not in general against examples in the library documentation, right? What do you think if I replace the first example with more cut-and-dry one, similiar to the ErrorT example?
I'm not so fussed when the example is at the bottom of the document, since it doesn't really effect much else. If people are going to want to improve/annotate the example ever, the wiki really is a great place to put it. I like examples, but I more like short and sweet examples - but thats just a personal preference. Not a global policy at all. Thanks Neil
participants (2)
-
Andriy Palamarchuk -
Neil Mitchell