On 21 July 2010 15:28, Richard O'Keefe
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.Miljenovic@gmail.com IvanMiljenovic.wordpress.com