I agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can pr

I agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can produce automatically from a codebase that does not contain lots of hints and extra documentation. A listing of classes and their methods is not even an adequate reference guide, let alone an adequate explanation of how to use the library and why it was written the way it was. As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.