3.12 How to Document a Perl Class with POD

An essential part of programming is documentation. Comments in the code are an important part of documenting code for those who have to read it or modify it in the future.

Equally as important is documentation for those who have to use the code. A short, accurate, practical guide to using a Perl class is absolutely necessary in order for the class to be generally useful.

Perl uses a language called POD (plain old documentation) to put documentation right in the code. The fourth and final version of Gene.pm has POD documentation embedded in it.

To gain access to the documentation, you merely have to type:

perldoc Gene.pm

in the same directory in which the Gene.pm lives. (For other options, see the perlpod manpage on the Web, or type perldoc perlpod .)

Given that this book contains copious amounts of explanation of the code, I've kept the POD documentation to a minimum. The POD language is simple; the best way to use it to write good documentation is to copy and modify the documentation style that's used by some other well-written module. You will almost always want to give a bit more information than the example shown here; try examining the documentation for some Perl modules on your computer, for example, perldoc CGI or, if it's installed, perldoc Bioperl .

The Perl interpreter will ignore everything from a line beginning:

=head1

up to a line beginning:

=cut

so you can embed your POD documentation in with your Perl code without difficulty.

It's also worth pointing out that many filters exist that will take your .pm file with its embedded POD documentation and produce versions of the documentation in HTML, LaTEX, plain text, nroff , or other formats.

Here's the output you get from typing perldoc Gene.pm :

Gene(3)        User Contributed Perl Documentation        Gene(3)

Gene
       Gene: objects for Genes with a minimum set of attributes

Synopsis
           use Gene;

           my $gene1 = Gene->new(
               name       => 'biggene',
               organism   => 'Mus musculus',
               chromosome => '2p',
               pdbref     => 'pdb5775.ent',
               author     => 'L.G.Jeho',
               date       => 'August 23, 1989',
           );

           print "Gene name is ",        $gene1->get_name(  );
           print "Gene organism is ",    $gene1->get_organism(  );
           print "Gene chromosome is ",  $gene1->get_chromosome(  );
           print "Gene pdbref is ",      $gene1->get_pdbref(  );
           print "Gene author is ",      $gene1->get_author(  );
           print "Gene date is ",        $gene1->get_date(  );

           $clone = $gene1->clone(name => 'biggeneclone');

           $gene1-> set_chromosome('2q');
           $gene1-> set_pdbref('pdb7557.ent');
           $gene1-> set_author('G.Mendel');
           $gene1-> set_date('May 25, 1865');

           $clone->citation('T.Morgan', 'October 3, 1912');

           print "Clone citation is ", $clone->citation;

AUTHOR
       A kind reader

COPYRIGHT
       Copyright (c) 2003, We Own Gene, Inc.

2002-11-25                 perl v5.6.1                    Gene(3)