Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

Note: This is a copy of (2003-04-23). The version on my website may be more up to date.

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 you 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!


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


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


    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<as_string>

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


=head1 AUTHOR

Juerd - <>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>



Documenting using POD is easy. Have fun!

Edit by tye, add READMORE

In reply to POD in 5 minutes by Juerd

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?

What's my password?
Create A New User
Domain Nodelet?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (5)
As of 2021-11-30 17:22 GMT
Find Nodes?
    Voting Booth?

    No recent polls found