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.
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.