Module Design and Implementation

Plain Old Documentation

Perl provides a very simple code documentation system called plain old docu 

mentation, or POD. POD allows you to place your documentation inline with your 

Perl code. POD can be translated into a number of formats HTML, text, manual 

pages, PostScript, and more. The perldoc command that you've been using to read 

Perl documentation is a POD formatter that formats POD to be read on your screen.

The primary strength of POD is its ease of use. You only need to know a couple 

commands to get started. POD commands always begin with an equal sign (=) and 

must start at the beginning of a line. Here's a minimal example that documents the 

function estimate():

=pod

($low, $high) = estimate($design_time, $loc)

This function computes an estimate for the amount of time required for

a project.  It takes two arguments   the amount of time spent on design in

hours and the expected number of lines of code.  The return value is a list

of two values, the lower and upper bounds on the time required in hours.

=cut

Everything between a =pod and a =cut is POD documentation. Perl knows to 

skip this stuff when it's compiling your module so you don't have to do any com 

menting to have it ignored.

POD is a paragraph oriented format. Paragraphs begin and end with blank 

lines. If the paragraph begins with white space, then it is considered a verbatim 

paragraph and no formatting is applied. This is useful for code examples where the 

spacing is important. The text in normal paragraphs will be automatically for 

matted in a number of ways the text will be wrapped and filled, plain quotes may 

be turned into smart quotes, and any embedded Perl identifiers will be made more 

visible. The actual details of the formatting are up to the individual formatter 

what makes sense in HTML may not make sense in a man page.

Modules typically have at least five sections: NAME, SYNOPSIS, DESCRIPTION,

AUTHOR, and SEE ALSO. The NAME section gives the module's name followed by a dash 

and a short description. The SYNOPSIS section shows some simple usages of the 

module. DESCRIPTION contains the bulk of the documentation, usually containing 

subsections for each function or method in the module. AUTHOR gives credit and 

contact information, and SEE ALSO contains references to external documents 

related to the module.

67

67