Mastering Perl for Bioinformatics [Electronic resources] نسخه متنی

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)