Doxygen (which seems to be uses by the majority of F/OSS projects) generates completely unreadable docs.
Every time I look into ICU docs (generated by Doxygen) I get lost for 10 minutes trying to find a function _by name_.
Well, in ICU there are two sets of docs - the automatic docs (e.g.
http://www.icu-project.org/apiref/icu4c/unum_8h.html) and the human docs (e.g.
http://icu-project.org/userguide/formatNumbers.html). Ideally, we should have both - the former is for checking the API, the latter is for actually understanding what it does. There's no way to get the latter doc except for actual person to write it. :)
The only problem is that you need to know the internals a bit (or at least want to learn it) to be able to document it, and all the people with this knowledge are busy with other things most of the time..
You can count on me if you need any help/hints, though.
Same here.
--
Stanislav Malyshev, Zend Products Engineer
stas@zend.com http://www.zend.com/