- Packages
- Modules
- Exporting symbols
- Some example modules
- Documenting modules with POD
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
6.5 Documenting modules with POD
Perl documentation is generally well written and complete. This is partly because of POD, the "plain old documentation" format that allows documentation to be interspersed in Perl modules. POD can be read by a number of different programs, including several that come with Perl—perldoc , pod2html (for HTML output), pod2latex (for L ATEX output), and pod2man (for Unix-style man pages).
6.5.1 POD definitions
POD directives are placed directly inside of a Perl module. POD recognizes three kinds of lines:
Regular lines of text are kept verbatim.
Indented lines of text are kept verbatim, but indented.
POD commands begin in the first column, and with an equals sign (=). This is how Perl distinguishes between code and documentation.
Each POD command typically affects a single paragraph of text. For example:
package Howdy; -head1 NAME Howdy - A module for testing cowboy-speak -head1 SYNOPSIS This module allows programs to display error messages in cowboy-speak, as well as plain ol' English. -head1 DESCRIPTION If you want to know what to say when tipping your 10-gallon hat, you can use this module. =cut
This module consists entirely of a package statement and POD documentation. POD's =head1 command introduces a first-class headline, and is used for the highest-level section headings. (There is a similar =head2 command for smaller headlines.) Headline text in =head1 sections is traditionally capitalized.
6.5.2 Writing and reading POD
The =cut command ends a section of POD. If the module contains several POD sections, it may contain several =cut commands. For example, the following module has three POD sections, each of which ends with =cut:
package PodTest;
=head1 NAME
PodTest - Demonstrates POD module
=head1 SYNOPSIS
use PodTest;
my $variable = $PodTest::a;
=head1 DESCRIPTION
This module demonstrates how to write POD documentation. It doesn't
do anything else. If you use this module, you deserve
what you get.
=cut
use vars qw($a $b $c);
$a = 1;
$b = 2;
$c = 3;
=head2 $a
The C<$a> variable contains 1.
=head2 $b
The C<$b> variable contains 2.
=cut
sub return_five
{
return 5;
}
1;
=head2 return_five
The subroutine C<return_five> returns C<5>.
=cut
The above module demonstrates single-letter POD commands, such as C and I, which modify the way in which a particular letter or word is displayed. C treats the text between < and > as literal code, I italicizes it, and B (not shown in the preceding example) makes it bold. Variable, subroutine, and module names are typically displayed using C<>.
Another useful single-letter command is L, which creates a link to another file, document, or section of a manual page. perldoc , which comes with Perl, is the easiest way to read POD documentation. Typing perldoc Module will look for that module in @INC , displaying its POD documentation. If the module does not exist, perldoc exits with an error message.