Programming Perl, 4th Edition

Documenting Your Perl Programs

We hope you document your code whether or not you’re a Random Hacker. If you do, you may wish to include the following sections in your pod:

=head1 NAME

The name of your program or module.

=head1 SYNOPSIS

A summary of the module’s use.

=head1 DESCRIPTION

The bulk of your documentation. (Bulk is good in this context.)

=head1 AUTHOR

Who you are. (Or an alias, if you are ashamed of your program.)

=head1 BUGS

What you did wrong (and why it wasn’t really your fault).

=head1 SEE ALSO

Where people can find related information (so they can work around your bugs).

=head1 COPYRIGHT

The copyright statement. If you wish to assert an explicit copyright, you should say something like:

Copyright 2013, Randy Waterhouse.  All Rights Reserved.

Many modules also add:

This program is free software.  You may copy or
redistribute it under the same terms as Perl itself.

One caveat: if you’re going to put your pod at the end of the file, and you’re using an _ _END_ _ or _ _DATA_ _ token, make sure to put an empty line before the first pod directive:

_ _END_ _

=head1 NAME

Modern – I am the very model of a modern major module

Without the empty line before the =head1, the pod translators will ignore the start of your (extensive, accurate, cultured) documentation.