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.
Get Programming Perl, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.