home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

Book Home Programming PerlSearch this book

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


A one-line description of what your program or module does (purportedly).


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


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:


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

Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.