Monday, March 16, 2009

Plain Old Documentation (POD)

Perl allows documentation to be integrated into your programs easily thanks to the Plain Old Documentation (POD) system.
Most modules from CPAN can be parsed for comments and documentation using the perldoc command from the shell.
For example, typing "perldoc Net::Twitter" will display information on the Twitter module (if installed). Perl will ignore Pod statements when parsing through the code.
This is a convenient way to always find documentation related to a given program, as the program contains the user manual within itself.

There are a few keywords to know, as well as basic principles.
Here are the two most basic statements:
=head1 TITLE

Super duper comment here

The Pod parser will behave differently if you write the text at the start of the line or if you type space or tab characters before.
  • Ordinary paragraphs will reformat your text (such as wrapping, justifying, etc.). Start writing on the first column, like in the example above.
  • Verbatim paragraphs will not be reformated. The first character of the text should be a space or a tab.
I'll let you read more details on the perldoc page.
Also, don't forget to add an empty line before and after each Pod command. Some parsers might get confused if you don't.
Use C<text> when writing an example of code, F<text> for file names and B<text> for shell command names.

The real cool thing about Pod is that you can sprinkle bits of comments all over the code.
I have rewritten to version 0.2.1 to follow perlstyle rules (mainly renaming variables and functions) and to add Pod comments.

The script can be found here.

As you will see, I have kept each part of the doc as close as possible to the relevant part of the code, such as in the first lines below:

use Modern::Perl;

=head1 NAME - Script to update your status on and/or identica


my $PROG_NAME = "";

=head1 VERSION

This is version 0.2.1


my $VERSION = "v0.2.1";
my $version_date = "March 7th 2009";




use Getopt::Long; # To parse the command line
use Net::Twitter; # API to and
This makes it easy to update the doc when the code changes.
Also, the get_help subroutine (the function formerly known as Help) has been rewritten to call the script in a reentrant sort of way with the system command:
sub get_help {
system("perldoc $0"); # $0 contains the name of the file containing the Perl script being executed
} # End of get_help
Larry Wall quote of the day:
"You have to admit that it's difficult to misplace the Perl sources. :-) "

When using Pod, you can also include documentation in Larry's statement.

No comments :

Post a Comment