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.