Learning Perl Objects, References amp;amp; Modules [Electronic resources] نسخه متنی

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.[8]

[8] 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.