I'm not sure how NAME could be considered optional. And I would consider COPYRIGHT to be essential for all but in-house modules (and important even then).

Hi

You might look at item 3 of this article by TheDamian to see what his template for a module is. I found it very useful.

There was a similar template for scripts on the London PM mailing list, but it currently seems to be having a massage.

- j

Also worth noting perlmodstyle. It has a section on documenting with Pod.

An alternative viewpoint is that for anything other than temporarially blocking out a chunk of code, POD should not be used. If these are programmers comments, then use comment cards.

If this is proper documentation, then use a proper documetnation tool/markup. Something that knows how to:

• build tables;
• include diagrams;
• build tables of contents;
• create indexes;
• knows how to hyperlink;

If you use the lowest common denominator, you reap what you sow.

About five years ago, I built a skeleton for Perl consisting of:

#! /usr/local/bin/perl

package FILL-IN-THE-NAME;

use strict;
use warnings;

CODE-GOES-HERE

1;

__DATA__

=pod

=head1 NAME

=head1 SYNOPSIS

=head1 DESCRIPTION

=head1 EXAMPLES

=head1 AUTHOR

=cut

Basically, I took the format of the UNIX man() pages and added the 'EXAMPLES' header. In addition, I have occasionally added 'TODO', 'NOTES', or 'SEE ALSO' headers when they were warranted. As I write the code, I update the POD.

I did this for a project that had all the ear-marks of becoming humongous (due to a certain lack of detail in the specifications and requirements). I could see myself quickly losing what little mind I had left if I didn't take steps. So I cooked up the template and started using it religiously.

Six months into the mess, I (finally) got another body assigned to the project. She was somewhat boggled by the idea of doing the Doco as you went along, but she came around.

What convinced her was her first bi-weekly 'status review meeting' with the "Project Team". I wandered in with a hundred and thirty-five pages of printed POD and spent the next three hours answering questions with variations on a theme of: 'Yes, that has been implemented, and see page mumble for the Doc'; and 'No, we can't do that, it will break the interface to X, unless we do the following .... ". (I wrote a bit of code that generated an Index from the 'NAME' headers and a Quick-Ref from the 'SYNOPSIS' headers to pull this off.)

Over the next eighteen months that 'structured documentation' saved our bacon so many times....

Private methods or subroutines can be commented rather than POD-ed, but their names should follow the leading underscore convention so they can be easily excluded from any coverage calculations.

I use normal POD for subroutines, but use the "=begin" pod command designate a different translator to process those sections. I call my programmer documentation sections "programmers" docs, and I created a little "translator program" that just identifies the programmerdocs sections, strips them out, and passes them on to the standard pod translators.

That way, 'perldoc' gives me the user documentation, and my 'programmerdocs' script gives me the programmer documentation. This also allows a tester who is unfamiliar with the program to black box test each function without knowing the internals of the code: if the code doesn't match it's documentation, one of them needs fixing. This would be more useful if we had a testing department, but hopefully it's still of use to document.

I consistantly use the same template for documenting each function: first the name and arguments, then a one line description of the purpose of the function, then a detailed description, then the return values section, the global variables used (indicating read/write status), any preconditions (such as open filehandles, etc.), any postconditions (program termination conditions, warnings emitted, filesystem modifications, etc).

By documenting the pre and post conditions carefully, I usually end up thinking about the error handling of my functions (ie. "the routine emits a warning: but should it throw an exception instead?" or "The program dies if we hit an error condtion. Can/should it recover from this state instead?"). Thinking about formally documenting my decisions makes me think harder about the justifications I have for making each of those choices.

That's what works for me. I don't claim it should work for anyone else, though. :-)
--
Ytrew

Back in the good old days, pod2man would complain if you would not have a NAME section (excpet if you used the --lax option). All my documentation starts with NAME, SYNOPSIS and DESCRIPTION, as good manual pages do. For me, POD is primary used to generate man pages, and hence, it should follow the man pages conventions, hence the first three sections. And while in extreme cases a SYNOPSIS or a DESCRIPTION may be omitted, NAME would not be optional.

As for other sections, BUGS, SEE ALSO, COPYRIGHT/LICENSE, AUTHOR/MAINTAINER, and HISTORY, I use frequently. To a lesser extent: EXAMPLES, FILES (if additional files, typically configuration files, are used by the program), STANDARDS (if it conforms to standards), REFERENCES (for instance, to literature).

I presume that you list methods in a section METHODS. I would describe methods in the DESCRIPTION section. I've no idea what to expect from sections named PUBLIC and PRIVATE.

Private methods or subroutines can be commented rather than POD-ed, but their names should follow the leading underscore convention so they can be easily excluded from any coverage calculations.

I would not document private methods in the POD - as I said, for POD is to generate manual pages. That is, user documentation. It should document the interface: what to pass in to the program, subroutines or methods, and what to expect to happen in return (return values, side-effects). Discussion of the internals should be kept to a minimum, and only done if relevant. Hence, no private methods.

I don't like having a (potentially) large number of subroutines starting with an underscore. It looks unnatural and distracts. Doing so for the reason you mention is double bad. Programming languages shouldn't force arbitrary rules upon a programmer - it's the programming language that should be the slave, and the programmer the master. Not the other way around.

Please be sure to look at Test::Pod and Test::Pod::Coverage to automate your checking. I think that Test::Pod::Coverage ought to be extensible enough to handle your substitute.