plainblack.com
Username Password
search
Bookmark and Share
Subscribe

Plain Old Documentation (POD)

WebGUI uses Perl's default documentation format called POD. 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. In WebGUI, we've standardized on putting the documentation inline with the code. That helps ensure that when the code is updated, the documentation is updated with it.

Headings

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

In WebGUI we use =head1 to denote a section of documentation, and =head2 to denote subroutines or methods, and =head3 to denote subroutine parameters.

Basic Formatting

Besides head tags, PODs basic formatting is based upon white space. For instance, each paragraph is seperated by a blank line. Indents (spaces or tabs) treat the paragraph as code. You should not indent your text unless it is supposed to be code.

Markup

There are about a dozen markup tags available in POD, but for most purposes only four are important.

  • B<bold text here>
  • I<italic text here>
  • C<code text here>
  • E<gt> (Entities)

You can also nest tags like this: B<bold I<and italics> text>

If you need to include a > character then you can do one of two things:

  • C<$foo-E<gt>bar>
  • C<< $foo->bar >>

Besides the named entity gt, you can also use decimal entities like E<30>.

Usage

perldoc filename.pm

Keywords: documentation

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved