On 21 July 2010 15:28, Richard O'Keefe <o...@cs.otago.ac.nz> wrote: > I'm giving some lectures this week about how to _read_ programs, > and I've had some things to say about JavaDoc and wondered whether > to show some examples of Haddock. > > I took a certain library that has been mentioned recently in > this mailing list. (I shall not identify it. The author deserves > praise for his/her contribution, not a public mauling, and the > reason for the message is that that package is not unusual.) The > reason I chose it was that I thought "actually, >>I<< should learn > how to use that, never mind the students." > > Upon looking at the Haddock web page, > - reaction one "this is pretty flashy". > - reaction two, "but WHERE IS THE DOCUMENTATION?"
These are good points and I agree with the rest of your email as well (which I've removed for the sake of brevity). However, I would like to offer two qualifiers that I myself have found when writing documentation for my own libraries: * When writing the code, it's obvious what it does; as such you may think any documentation you may offer is trivial (down the track, however...). * The author is familiar with a library; as such it may not be obvious what extra documentation could be needed. As such, if you're a user of a library and you think it's documentation could be improved, maybe try telling the maintainer that (this kind of prompting is why I bothered to make a website for my graphviz library). As a kind of a wishlist, having more markup support would possibly improve the quality of documentation (rather than being limited to normal text, monospace text and italic text; I've often times wanted to make something bold in my Haddock documentation to emphasise it but alas Haddock doesn't support it). -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
