News for hackers. Stuff that matters.
Re:The Most Important Language Feature No One Talks About by DougWebb on Monday October 19, 2009 @08:54AM (#889969)
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.

Re:The Most Important Language Feature No One Talks About by eru on Monday October 19, 2009 @08:59AM (#889976)
The Perl module documentation seems to be modelled on man pages.
Re:The Most Important Language Feature No One Talks About by DougWebb on Thursday October 22, 2009 @04:25PM (#897577)
Yep. And sometimes Perl module documentation can be as bad as man pages can be. Good guidelines for how to document are not sufficient; good technical documentation skills are necessary as well.