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:

view plainprint?

1. =head1 TITLE  
2.   
3. Super duper comment here  
4.   
5. =cut  

=head1 TITLE

Super duper comment here

=cut

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 twit.pl 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:

view plainprint?

1. #!/usr/bin/perl  
2. use Modern::Perl;  
3.   
4. =head1 NAME  
5.   
6. twit.pl - Script to update your status on twitter.com and/or identica  
7.   
8. =cut  
9.   
10. my $PROG_NAME = "twit.pl";  
11.   
12. =head1 VERSION  
13.   
14. This is version 0.2.1  
15.   
16. =cut  
17.   
18. my $VERSION   = "v0.2.1";  
19. my $version_date = "March 7th 2009";  
20.   
21. =head1 DEPENDENCIES  
22.   
23. Getopt::Long  
24. Net::Twitter  
25.   
26. =cut  
27.   
28. use Getopt::Long;   # To parse the command line  
29. use Net::Twitter;   # API to twitter.com and identi.ca  

#!/usr/bin/perl
use Modern::Perl;

=head1 NAME

twit.pl - Script to update your status on twitter.com and/or identica

=cut

my $PROG_NAME = "twit.pl";

=head1 VERSION

This is version 0.2.1

=cut

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

=head1 DEPENDENCIES

Getopt::Long
Net::Twitter

=cut

use Getopt::Long;   # To parse the command line
use Net::Twitter;   # API to twitter.com and identi.ca

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 twit.pl script in a reentrant sort of way with the system command:

view plainprint?

37. sub get_help {  
38. system("perldoc $0"); # $0 contains the name of the file containing the Perl script being executed  
39. exit;  
40. } # End of get_help  

sub get_help {
system("perldoc $0"); # $0 contains the name of the file containing the Perl script being executed
exit;
} # 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.