Approaches to Web Development for Bioinformatics

Medical Computing > Web Development for Bioinformatics > Application Development > Perl > Perl Documentation

Perl Documentation (POD)

POD aka Plain Old Documentation, aka Perl Online Documentation is a way of documenting Perl code so that users of your code do not have to read the code itself. Using the # style of comments is OK if you are the only one reading using your code. However, even if you are not ready to distribute you module on CPAN you may have someone else using your code. POD documentation style allows you to replace the # comments with documentation that can be extracted to a separate text or HTML file. Here is an example of how it works using the program above.

#!/usr/bin/perl -w

package MedicalComputing::GeneInfo;

=head1 NAME
MedicalComputing::GeneInfo
An example Perl module to demonstrate object oriented features with a gene_info record

=head1 SYNOPSIS

use MedicalComputing::GeneInfo;
MedicalComputing::GeneInfo->new($id, $symbol, $name);
id();
printGeneInfo();

=head1 DESCRIPTION

This class encapsulates a gene information record. Example usage is

use MedicalComputing::GeneInfo;
my $geneInfo1 = MedicalComputing::GeneInfo->new("3064", "HD", "Huntington Disease");
print "The ID is ", $geneInfo1->id(), "\n";
$geneInfo1->printGeneInfo();

=over

=item new($id, $symbol, $name)

A constructor for a GeneInfo instance
Required parameters
$id - the NCBI identifier field
$symbol - The gene symbol
$name - The name of the gene

=cut

sub new {

my $class = shift;
my $id = shift;
my $symbol = shift;
my $name = shift;
bless {ID => $id, Symbol => $symbol, Name => $name}, $class;

}

=item id();

An accessor method for the NCBI identifier field. The method does not expect any parameters.

=cut

sub id {

my $self = shift;
$self->{ID};

}

=item printGeneInfo();

A method to print all the fields to standard out. The method does not expect any parameters.

=cut

sub printGeneInfo {

my $self = shift;
print "GeneInfo\n",

"\tID:\t", $self->{ID}, "\n",
"\tSymbol:\t", $self->{Symbol}, "\n",
"\tName:\t", $self->{Name}, "\n";

}

1;

The =head1 and =item tags start a comment and tell the Perl interpreter to ignore the text. The =cut tag tells the Perl interpreter to start interpreting instructions again. The comments / documentation can then be extracted with the command

>perldoc -t GeneInfo.pm > GeneInfo.txt

The result is in file GeneInfo.txt. See perldoc and perlpod for more details.

Previous Contents Next

References

Contributed Comments and NotesAdd a comment.

There are no user comments.

Please send ideas and opinions by email at alexamies@gmail.com.