2 ms·
"There’s no substitute for documentation written, organized, and edited by hand." Which, in the case of rdoc and javadoc, are the docs written as comments with
by jamesbritt 17y ago
"There’s no substitute for documentation written, organized, and edited by hand."
Which, in the case of rdoc and javadoc, are the docs written as comments with the code.
If you assume auto-generated docs are nothing but class and method names, then yes they are weak. But there is real value in having the docs right there with the code; much easier to keep in sync, for example. The thing is, whether inline or in separate files, someone has to feel motivated to write them.
It makes me wonder just how familiar the author is with these particular tools. Linking to an rdoc sourceforge page, for example, tells me the author does not know that rdoc has been part of Ruby's stdlib for a few years now, and may never have even used it.
The big issue here is culture, not tools. Some number of Rubyists boasts of Ruby's eminent testing culture. I wish I would hear the same enthusiasm for a robust documenting culture as well; because all the needed tools exist but aren't sufficient.