Are there any conventions for writing POD comments for Perl?

Question

I was able to find a page from Safari Books Online that provides a template, but having never written POD comments, I'm not sure how good it is or if it is missing anything that might be considered convention to include.

What are the conventions to follow when writing POD comments for Perl scripts? Is there anything like Sun's Javadoc Conventions, but for POD comments?

Answer 1

It's not elaborate, but I like Juerd's perlpodtut introduction a lot.

The author mentions what he considers common sections and what they would include.

Answer 2

There are a set of recommendations in Perl Best Practices. The whole of Chapter 7 covers documentation, using POD, and the best approaches to documentation for modules, large projects etc. It also talks about CPAN conventions. That's probably your best bet.

Answer 3

Perl::Critic provides the following policies:

• Perl::Critic::Policy::Documentation::PodSpelling

• Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName

• Perl::Critic::Policy::Documentation::RequirePodAtEnd

• Perl::Critic::Policy::Documentation::RequirePodSections

A list of required sections is provided by the last policy above.

Module::Starter::PBP will generate the boilerplate code for you.

Answer 4

You can look at the Pod for the Perl modules on CPAN Search and quickly note the things that everyone does. The various module starting tools make boilerplate for you.

That's about as close as you'll get to guidelines.