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

Common sections

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.

Code examples

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.

Markup

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-E<gt>bar>
• C<< $foo->bar >> (inner whitespace is required!)
• C<<< $foo->bar >>> (inner whitespace is required!)

Entities

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

Lists

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:

perldoc perlpod

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

Conclusion

Documenting using POD is easy. Have fun!