Module PODs

The documentation for Perl modules is written in a simple markup language called POD (Plain Old Documentation).

This page shows how to write a POD for a Perl module. If you adhere to this style, then it will be easier for others to read and understand your documentation.

h2xs puts a skeleton POD at the end of the .pm file that it writes. Read the PODs in existing modules for additional examples.

=head1 NAME

Geometry::Circle - manages a circle
The NAME section gives the name of the module and a one-line description.

The name and description are separated by a dash. It is important to adhere to this format so that the POD can be converted to a proper man page.

=head1 SYNOPSIS

  use Geometry::Circle

  $circle  = new Geometry::Circle $x, $y, $r

  ($x, $y) = $circle->center;
  $radius  = $circle->radius;
  $area    = $circle->area

  $pi      = $Geometry::Circle::PI;
The SYNOPSIS section shows the essential steps in using the module: the use statement, any subroutines, class methods or variables, and all object methods. Method calls should indicate their parameters and return values.

Indent each line in the synopsis. This makes it a verbatim paragraph, and ensures that your alignment will be preserved.

=head1 REQUIRES

Perl5.8.8, Exporter, Geometry::Point
The REQUIRES section tells the user what they will need in order to use the module.
=head1 EXPORTS

Nothing
The EXPORTS section tells the user what the module will do to their namespace if they use it.
=head1 DESCRIPTION

Geometry::Circle manages circles.  
Methods are provided for creating 
circles and computing their areas.
This is a description of the module.

It should be written in terms that are relevant to the user, rather than the programmer.

  • What does it do for the user?
  • How do you use it?
  • What objects does it support?
  • What methods does it provide?
=head1 METHODS

=head2 Creation

=over 4

=item new Geometry::Circle $x, $y, $radius

Creates and returns a 
new Geometry::Circle object 
with center ($x, $y) and radius $radius.

=back

=head2 Access

=over 4

=item $circle->center

Returns a list of the x,y coordinates 
of the center of the circle.

In scalar context, 
returns an array reference.

=item $circle->radius

Returns the radius of the circle.

=item $circle->area

Returns the area of the circle.

=back
The METHODS section lists and describes each method in the class.

You may further organize methods under level-2 headings, such as Creation, Access and Utility.

=head1 CLASS VARIABLES

=over 4

=item $Geometry::Circle::PI

The ratio of the circumference 
of a circle to its diameter.

=back
The CLASS VARIABLES section lists any package variables in the API.
=head1 DIAGNOSTICS

=over 4

=item Negative radius

(F) A circle may not be created with a negative radius.

=back
The DIAGNOSTICS section gives the text of every error message the the module may generate, and explains its meaning.

Error messages are classified as follows:

(W)
A warning (optional)
(D)
A deprecation (optional)
(S)
A severe warning (mandatory)
(F)
A fatal error (trappable)
(X)
A very fatal error (non-trappable)
=head1 AUTHOR

A. U. Thor, a.u.thor@a.galaxy.far.far.away
You should include your name and email address, in case anyone needs to contact you regarding the module.
=head1 SEE ALSO

perl(1), Geometry::Square
This is the usual list of related programs and modules.
=cut
The =cut line denotes the end of POD text.

Some people distribute POD sections throughout their source code. Perl recognizes the POD sections and ignores them.


There is a Bulgarian translation of this page courtesy of All Science
Steven W. McDougall / resume / swmcd@world.std.com / 1997 June 2