Perl documentation with POD and Pdoc

I just finished writing a Perl module yesterday–it’s an implementation of the interval tree data structure. For code like this (anything that I may ever want to reuse and/or share), I try to include some documentation. In Perl, that usually means a few comment lines here and there. This is sufficient small scripts, but for larger programs or modules there are better alternatives (i.e. Perl’s Plain Old Documentation or POD). I figured this new module be a great chance for me to try out some new documentation approaches.

Perhaps the biggest reason I wanted to try out POD is that you can process POD-documented modules and produce nice HTML files. I use the BioPerl docs quite often (here is an example), and I wanted to create something like that for my module. I knew little about POD, so I figured I would look at the source code of several familiar BioPerl modules on my system. Surely enough, the files included the POD, so I used this as an example of how to document my module. All in all, it took less than an hour to add some comprehensive documentation. Here is a sample of the code.

=head2 find

 Title   : find
 Usage   : my @overlapping_intervals = $itree->find( 27000, 310000 );
 Function: Finds all of the intervals in the tree that overlap with the given
 Returns : An array of interval objects
 Args    : Two integers, representing the start and end positions of an interval

sub find
  my($self, $start, $end) = @_;
  my @overlapping = ();

  # Grab overlapping intervals from this node
  foreach my $interval(@{$self->{intervals}})
    push(@overlapping, $interval) if($interval->end() >= $start and $interval->start() <= $end);
  # Grab overlapping intervals from the left subtree
  if( exists($self->{left}) and $start <= $self->{center} )
    @overlapping = (@overlapping, $self->{left}->find($start, $end));
  # Grab overlapping intervals from the right subtree
  if( exists($self->{right}) and $end >= $self->{center} )
    @overlapping = (@overlapping, $self->{right}->find($start, $end));

  return @overlapping;


Once I was finished, I ran pod2html on the module source code and got this (source here). Definitely not what I was expecting. I mean, the BioPerl docs aren’t exactly the face of beauty themselves, but this just seemed…elementary to me.

I asked the BioPerl mailing list what tool they used for their documentation, and they referred me to the Pdoc package. Downloading the package from their site and installing it on my MacBook was pretty simple.

cd /usr/local/
sudo mv ~/Downloads/pdoc-1.1.tar.gz .
sudo tar xzf pdoc-1.1.tar.gz
cd pdoc-1.1
sudo perl Makefile.PL
sudo make
sudo make install

Running the tool was pretty simple as well. It has many command-line options for customization, but I used the bare minimum: the -source option for indicating the directory where my module was located and the -target option for indicating where to write generate output files.

mkdir html_docs_temp
perl /usr/local/pdoc-1.1/scripts/ -source ~/interval_tree_temp -target ~/html_docs_temp

This created an entire documentation browser at ~/html_docs_temp/index.html. It definitely looks much better than the previous example, and while the browser idea is nice (I will be using it in the very near future), all I really needed for this simple example was the IntervalTree.html and the perl.css file. Here are the results (source here).


One comment

  1. Pingback: Setting up {OpenGrok for source code browsing « BioWize

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s