Programming Perl, 3rd 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 one-line description of what your program or module does (purportedly).

=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.