Asking for good examples of POD is a little like asking for
good examples of a web page. What's good depends on the complexity
of your module, your development needs, your production
environment, and even your personal style. There is a lot of
variety in both visible content and internal placement of the
POD that creates the content. I'll highlight a few points here,
but my recommendation is that you study some CPAN modules and ask
yourself "What works (communicates well) and why?" Then develop a
style of your own.
There is a basic skeleton that many of the CPAN modules
seem to follow. This consists of the following sections:
- NAME section - name of function in bold followed
by a one line description.
- various descriptive sections - often this is divided
into two sections. The first is a SYNOPSIS section
that gives a quick thumbnail sketch of the module's
capabilities, usually via sample code or a list of
function/methods. The second is a much longer section titled
DESCRIPTION. This covers all the points that may not
be obvious from the synopsis. However, the number and
organization of the description sections can vary a lot
depending on the complexity of the module
- CAVEATS (sometimes titled "BUGS AND CAVEATS",
"NOTES AND CAVEATS", "NOTES" or "BUGS")
- one or more sections listing known bugs, unrealized
implementation goals, and general restrictions on
use contexts - for example: operating system limitations or
whether or not the module plays well with Apache and
mod_perl
- SEE ALSO - section listing related modules. Modules
can be related because they do the same thing a different way,
provide helpful background information or because they are a
useful complement to module at hand. Sometimes you will also
see a brief description explaining why they should be "seen
also".
- AUTHOR - section listing everyone who wrote or helped
with the module.
- COPYRIGHT - section listing who holds the copy rights
and licensing agreements.
-
To sort out what information belongs in your description
sections is probably the hardest part of writing good POD. A lot
depends on the complexity of your module:
- Do you have a purely functional interface? An OO interface?
Both?
- Do your functions or methods have a lot of similar
parameters?
- Do they fall naturally into groups that should be
discussed together? Do they have a natural order of
application - i.e. first use method A, then B, then
C?
- Are the parameters simple scalars, arrays, and hash
references? Or are there parameters that need significant
explanation - for example, a subroutine that takes a
special set of parameters; a hash with a list of keys
with special meanings; a string that is a mini-language
in its own right; or a string, hash, or array that
must be created
- Is the reason for each function obvious or do you need
to provide background information and context so that
users understand why each function exists and when it
would be appropriate to use?
If the parameters are simple and the role of each function
is pretty obvious from its name, you may be able to get away with
documentation that consists of a brief SYNOPSIS
section followed by a DESCRIPTION section briefly
describing each function and its parameters one by one.
If there are a lot of similarly defined parameters, it is
often a good idea to have the synopsis section use consistent
variable names for each parameter. Then include a subsection of
DESCRIPTION explaining what values parameters
$x, $y, $mumblefoo can take. This can save a lot of time for your module user: without users
have to scan back and forth between your individual function
descriptions to figure out if $x in
makeFred($x) has the same meaning as $x in
in makeBarney($x). Not fun.
For more complex modules, its hard to come up with rules of
thumb, so I refer you back to the original advice: study a variety
of CPAN modules and ask yourself - what does and does not get its
point across and make the module easier to use?
Once one has figured out what to document, the next question is
where to document. There are several styles and I don't know that
one is right - they suit different programming styles, maintenence
and production needs:
- close to the code - some people like to keep function
and method descriptions next to the code they document. If you are
going to use this approach, you'll have to mentally divide your
documentation into three groups: stuff before the functions, the
functions and stuff after. The POD for stuff before (e.g.
NAME, SYNOPSIS would go at the top of your source
file. The stuff after (e.g. CAVEATS, AUTHOR, etc)
goes at the bottom.
- in the file but out of the way - some people feel that
keeping documentation, especially lengthy documentation close to
each function makes it difficult for them to get a good birds eye
view of a module. This is particularly true if your team has a
lot of people that are very fluent in reading code. To get POD
out of the way, some people prefer to place all of the POD at the
top or the bottom
- separate file - you can also place your pod in a file
that has the same name as your module but ends in .pod
rather than .pm. This is a good approach if your
module is complex and requires lengthy documentation. Its a bit
of waste of parser power and CPU time to chomp through lengthy
documentation just to get at a few lines of code. The down side of
this approach is that it takes more work to keep the interface
described in the documentation in sync with the code.
One final issue relating to POD is the role of "hidden POD".
POD can be used for many things including in-line test cases,
private developer notes, and cook book examples. The normal
document generator will quietly ignore =foobar if
it doesn't know what foobar is supposed to mean.
There are numerous modules on CPAN that take advantage of this
feature to embed all sorts of maintenence related information
in source code files. For example, see Test::Inline
for inline test cases and Test::Cookbook for cookbook
examples that double as executable code. (Note: I don't use
either of these modules - so I can't vouch for their safety)
Best, beth