Embedded Documentation (Learning Perl Objects, References & Modules)

13.4. Embedded Documentation

Immediately following the mandatory true value in the file, you'll find the _ _END_ _ marker:

_ _END_ _

This marker tells Perl that there's no Perl code anywhere later in the file and that the Perl parser can stop now.[83]

[83]The data immediately following the _ _END_ _ marker is available by reading from the DATA filehandle, which is a great way to include a small amount of constant data with your program. However, that's not why we're doing that here.

Following the _ _END_ _ marker, you'll find the embedded documentation for the module:

# Below is stub documentation for your module. You'd better edit it!

=head1 NAME

Island::Plotting::Maps - Perl extension for blah blah blah

=head1 SYNOPSIS

  use Island::Plotting::Maps;
  blah blah blah

=head1 ABSTRACT

  This should be the abstract for Island::Plotting::Maps.
  The abstract is used when making PPD (Perl Package Description) files.
  If you don't want an ABSTRACT you should also edit Makefile.PL to
  remove the ABSTRACT_FROM option.

=head1 DESCRIPTION

Stub documentation for Island::Plotting::Maps, created by h2xs. It looks like the
author of the extension was negligent enough to leave the stub
unedited.

Blah blah blah.

=head1 EXPORT

None by default.



=head1 SEE ALSO

Mention other useful documentation such as the documentation of
related modules or operating system documentation (such as man pages
in UNIX), or any relevant external documentation such as RFCs or
standards.

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

=head1 AUTHOR

Ginger Grant, <ginger@island.cocoanet>

=head1 COPYRIGHT AND LICENSE

Copyright 2002 by Ginger Grant

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. 

=cut

This documentation is in POD format. The perlpod manpage describes the POD format in detail. Like Perl itself, POD is said to mean various things, such as Perl Online Documentation or Plain Old Documentation, and so on. To most of us, it's just POD.

As the template describes, you're expected to edit portions of this text to fit your particular module. In particular, leaving the blah blah blah is considered bad form.

The POD information is extracted automatically by the installation process to create the native documentation format, such as Unix manpages or HTML. Also, the perldoc command can locate POD in the installed scripts and modules and format it for the screen.

One nice thing about POD is that it can be interspersed with the Perl implementation code it describes. For example, from Chapter 12, you needed three subroutines for the Island::Plotting::Maps module. You can commingle the code and documentation. Each POD directive (a line beginning with an equal sign) switches from Perl mode (lines interpreted as Perl code) to POD mode (lines interpreted as documentation), and each line beginning with =cut switches back. Thus, the resulting file looks something like:

package Island::Plotting::Maps;
[... stuff down to the $VERSION setting above ...]

=head1 NAME

Island::Plotting::Maps - Plot maps on the island

=head1 SYNOPSIS

  use Island::Plotting::Maps;
  load_map("/usr/share/map/hawaii.map");
  scale_map(20, 20);
  draw_map(*STDOUT);

=head1 DESCRIPTION

This module draws maps.  [ more here ]

=over

=item load_map($filename)

This function [ more here ].

=cut

sub load_map {
  my $filename = shift;
  [ rest of subroutine ]
}

=item scale_map($x, $y)

This function [ more here ].

=cut

sub scale_map {
  my ($x, $y) = (shift, shift);
  [ rest of subroutine ]
}

=item draw_map($filehandle)

This function [ more here ].

=cut

sub draw_map {
  my $filehandle = shift;
  [ rest of subroutine ]
}

=back

=head1 SEE ALSO

"Map Reading for Dummies", "First Mates: why they're not the captain",
and be sure to consult with the Professor.

=head1 AUTHOR

Ginger Grant, <ginger@island.cocoanet>

=head1 COPYRIGHT AND LICENSE

Copyright 2002 by Ginger Grant

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. 

=cut

1;

As you can see, the documentation for the subroutines is now very near the subroutine definition, in hope that as one gets updated, the other will be similarly changed. (Out-of-date documentation is often worse than no documentation at all because at least with no documentation at all, the user is forced to look at the source code.) Many modules in the CPAN do this. The penalty is a very slight increase in compile-time activity because the Perl parser has to skip over the embedded POD directives.

Whether you place your POD at the end of the file (as the template suggests) or intertwined with your code (as presented in the preceding paragraphs) the important thing to remember is always document your code. Even if it's just for you, a few months later, when your brain has been 42,000 other places before you look at the code again, you'll be glad to have those notes. Documentation is important.