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 smile
  • 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!


    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>
  • 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!)


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.


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:


   "new"       Returns a new
               My::Module object.
   "as_string" Returns a stringified
               representation of the object.
               This is mainly for debugging

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


        use My::Module;
        my $object = My::Module->new();
        print $object->as_string;


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

Returns a stringified representation of
the object. This is mainly for debugging


=head1 LICENSE

This is released under the Artistic License. See L<perlartistic>.

=head1 AUTHOR

Juerd - L<>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>



Documenting using POD is easy. Have fun!

-- VitalyDruzhinin - 2011-09-20
Topic revision: r1 - 2013-08-28, VitalyDruzhinin

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback