Code documentation style guidelines for Perl?

Question

Does anyone know of a perlstyle-like guideline for how to document Perl code? Like this bit from javadoc guidelines:

"Gets the label of this button.         (preferred)" vs.
"This method gets the label of this button.          (avoid) "

(from http://java.sun.com/j2se/javadoc/writingdoccomments/). I haven't found anything at perlstyle or in Extreme Perl - Coding Style. PBP maybe?

Answer 1

There is a good writeup about Perl Coding Standards at the following link, which will bring you the Documentation Standards section.

Perl Coding Standards - Documentation

Answer 2

• Damien Conway's book Perl Best Practices devotes a chapter to documentation.

• perldoc perlstyle gives some quick guidelines for pod documentation (more at perldoc perldoc) -- it's always nice when a module has its own built-in POD documentation.

• I believe perlcritic gives some documentation suggestions too (hook into your code with Perl::Critic).

Answer 3

Try http://search.cpan.org/perldoc?perlmodstyle and the documents perlmodstyle references.