File-level POD Usage

This page describes the way we tend to document our Perl files.

Most of what we do begins with copying two sections of an existing file to the new file we're generating. Sometimes we copy an entire file and gut it, or rename all the functions, but the general approach is the same.

We'll use the source file for Doxygen::Item::File as our example.

File Header

The top of the file, the file's header, looks like:

package Doxygen::Item::File;

=head1 NAME

Doxygen::Item::File - Input file to Doxygen and its comments and contents.

=head1 SYNOPSIS

    my  $cls = new Doxygen::Item::File;

=head1 ABSTRACT

A Doxygen::Item::File object represents an imaginary C/C++
source file for processing by the Doxygen documentation system.
These objects should be created by a specific source-language filter
(subclass of Doxygen::Filter, named Doxygen::I<language>::Filter)
when processing a source file.

=head1 DESCRIPTION

=head1 METHODS

=over

=cut

use     5.005;  # just to pick something, but not really tested
use     strict;
use     warnings;
use     UNIVERSAL   qw(isa);

use     base qw(Doxygen::Item);

our $VERSION = '0.01';

We begin with the package declaration. If we place any POD or doxygen comments before the package declaration it will be attached to the file as a whole, which isn't usually useful. After the package declaration we place the POD for the module.

Note that at the end we define a =head1 named METHODS, then an =over, then the =cut. This specific sequence is intended to work with POD as well as Doxygen. When processed by a normal POD tool the it generates a section, METHODS, which has items for each function. Using Doxygen and DoxyFilt the entire section (because of its specific name) is removed in favor of the Doxygen table of contents.

After the package's POD we specify the normal beginning of the package source, use statements and so forth. Then comes the bulk of the source code.

File Footer

At the bottom of the file, the file's footer, we place:

1

__END__

=back

=head1 SEE ALSO

DoxyFilt.pl, Doxygen::Item, Doxygen::Filter

=head1 AUTHOR

Marc M. Adkins, L<mailto:Perl@Doorways.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2004-2010 by Marc M. Adkins

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

=cut

The 1 is the return value for the package. Otherwise it won't compile properly.

After that we use an __END__ to break off compilation. This isn't strictly necessary because we're going to write more POD on the end, but it doesn't hurt either, and we just copy this stuff around so it doesn't much matter.

The first piece of POD is the =back line. Remember the way we ended the header with =over even though we had just started the METHODS heading? Well, now that we've defined all of our functions or methods, it's time to end that list.

Then we dump in whatever boilerplate we like at the end of each page. This varies from project to project.