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.

Translations

Indonesian
Macedonian courtesy of Elena Simski
Norwegian courtesy of besteonlinecasinoinorge.com
Portuguese courtesy of Artur Weber
Russian courtesy of Sandi Wolfe
Urdu courtesy of Samuel Badree

This work is licensed under a Creative Commons Attribution 4.0 International License.

Steven W. McDougall / resume / swmcd@theworld.com / 1997 June 2

=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.