Embedded Documentation






Embedded Documentation

Immediately following the mandatory true value in the file, you'll find the _ _END_ _ marker. That's double underscore followed by END followed by another double underscore. It's at the beginning of the line and has a newline immediately following it:

_ _END_ _

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

[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. Each POD directive (a line beginning with an equals 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. For example, you had three subroutines in the Island::Plotting::Maps module. The resulting file with mixed code and documentation 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, <[email protected]>

=head1 COPYRIGHT AND LICENSE

Copyright 2006 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 the 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 to 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.



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows