Home > Articles > Web Development > Perl

Modules in Perl

  • Print
  • + Share This
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.

  • + Share This
  • 🔖 Save To Your Account