Writing POD documentation and help for the program
Plain old documentation (POD) is a way to document a Perl script inside the script itself. The
command will tell you more about POD documentation and its syntax. Good
POD documentation means that users can access help for your program
quickly and efficiently. Take the time to learn the POD syntax; writing
manuals will be much easier. In addition, POD is compatible with a
variety of manual formatters, so you can generate a plain text file, a
UNIX-style man page, and a professional-looking LaTeX file from the
same documentation. POD is a fairly limited format, but perfectly
sufficient for most documentation needs.
Generally, the following
sections should be present in POD documentation: NAME, SYNOPSIS,
DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS, EXAMPLES,
ENVIRONMENT, FILES, CAVEATS/WARNINGS, BUGS, RESTRICTIONS, NOTES, SEE
ALSO, AUTHORS, HISTORY (from
perldoc pod2man, where you can find more information on each section; keep in mind that these are suggestions rather than imperatives).
Some programmers make the
-h switch to their programs invoke perldoc on the program, so the POD documentation is printed out as if the user had typed
perldoc whodunit.pl. The problem here is that a user doesn't want too much extra information from the
switch. He just wants the synopsis and the list of options. Thus, it is
better to write separate help handlers arising from the use of the
Note the documentation of
itself. Also, the the appearance of the POD documentation and other
online help is important. The first place a user goes is not the
manual. It's much more convenient to use the
flag, or look at the POD documentation. Note the alignment of the
colons, the spacing between lines, and the overall neatness. Outward
appearances do matter, often more than the actual functionality
provided by the program. Well-written programs should have good
documentation first and foremost.
Some programmers like to include POD documentation in their program instead of regular comments. Such POD comments begin with
=pod on a line by itself (there are other options, explained in the perlpod documentation), and end with
=cut on a line by itself. The
=pod line tells the Perl compiler to stop interpreting everything until the
=cut line, in effect excluding that block of text from the script itself.
This is fine if your users are also programmers, but may confuse normal
users who just want to look at the documentation for the script, not
the comments for the code itself. This approach also scatters
documentation throughout the code. Use it with restraint.