Plain Old Documentation in 5 minutes
Documentation is important
We all know that, and everyone knows why. I'll skip this section because any detailed discussion of why documentation is important would break my promise that you can learn to document in five minutes.
Documentation in Perl
Perl source code can contain documentation in POD format. POD stands for Plain Old Documentation. You can either mix POD with code, put the POD at the beginning of the file or put the POD at the end of the file. This depends only on what you like. You choose.
Headings in POD
Logical structure is important. So we use headings. There are four levels, and this should be enough. We use the =head1 .. =head4 commands (They are called command paragraphs officially. They are paragraphs because they're separated from the rest of the POD by blank lines).
=head1 NAME My::Module - An example module
To keep things clear, we all use the same sections everywhere. You already saw the NAME section. Yes, it is customary to write head1 paragraphs in ALLCAPS. If you author modules for CPAN, you have to use this style. If not, or if you use POD for other purposes than code documentation (it is a great format to write articles and reports in), it is your own choice.
- NAME contains the module or script name, a dash and a short description.
- SYNOPSIS means "see together" and shows example usage.
- DESCRIPTION contains a long description of what the module does and lists functions.
- BUGS or CAVEATS tells about bugs or issues the user should know about.
- ACKNOWLEDGEMENTS is where you thank bug fixers, testers and your parents.
- COPYRIGHT or LICENSE mentions copyright restrictions. Don't put the entire GPL there, though :)
- AVAILABILITY says where newer versions can be pulled from.
- AUTHOR explains who made it, if COPYRIGHT didn't already do so.
- SEE ALSO refers to additional documentation.
Those are all for =head1.
Functions, methods and things like that are usually explained in a =head2 within DESCRIPTION.
At the very least, document what arguments a function takes and what the function returns. If there is any precondition, mention it. If your function returns undef on error, let people know!
It is okay to write short sentences. Avoid long sentences.
Indented paragraphs render as code, with indenting intact. It's that easy!
=head1 SYNOPSIS use My::Module; my $object = My::Module->new(); print $object->as_string;
This is called a verbatim paragraph.
POD supports a small set of markup elements. To keep my time promise, I'll just list them:
- B<bold text here>
- I<italic text here>
- U<underlined text here>
- C<code text here>
- B<and you can I<nest> them>
And there are F, S, X and Z, but they're rarely used so not worth explaining in a simple tutorial.
If you ever need to include a > character within a formatting code, you have two options. If you want to render $foo->bar in a code font, this is what you can do:
- C<< $foo->bar >> (inner whitespace is required!)
- C<<< $foo->bar >>> (inner whitespace is required!)
You saw how E can be used for entities. These are like HTML entities, with the addition of:
- verbar for a vertical bar
- sol for a slash (solidus)
Numeric entities are decimal, octal (prefixed with 0) or hexadecimal (prefixed with 0x).
An example is much clearer than an explanation here.
=head2 Methods =over 12 =item C<new> Returns a new My::Module object. =item C<as_string> Returns a stringified representation of the object. This is mainly for debugging purposes. =back
As you can see, we start this definition list with =over and we end it with =back. In between are =items. The number after over is the indentlevel, used mainly by text renderers for a nice horizontal layout. pod2text renders the previous example as:
Methods "new" Returns a new My::Module object. "as_string" Returns a stringified representation of the object. This is mainly for debugging purposes.
Other POD coolness
You can use L to link to sections and other documents. Pod is ended with =cut to go back to Perl. There are special commands for different output formats. To read the complete POD documentation, type on a command prompt:
A complete example
=head1 NAME My::Module - An example module =head1 SYNOPSIS use My::Module; my $object = My::Module->new(); print $object->as_string; =head1 DESCRIPTION This module does not really exist, it was made for the sole purpose of demonstrating how POD works. =head2 Methods =over 12 =item C<new> Returns a new My::Module object. =item C<as_string> Returns a stringified representation of the object. This is mainly for debugging purposes. =back =head1 LICENSE This is released under the Artistic License. See L<perlartistic>. =head1 AUTHOR Juerd - L<http://juerd.nl/> =head1 SEE ALSO L<perlpod>, L<perlpodspec> =cut
Documenting using POD is easy. Have fun!