Plain Black, makers of WebGUI - Plain Old Documentation (POD)

Plain Old Documentation (POD)

View
Edit

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

Keywords:

Title
Attachment(s)
Content	<p>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. </p><div class="content"> <p><a name="idsYkvqmFVQvO8VZpoPAjihw" title="idsYkvqmFVQvO8VZpoPAjihw"></a></p> <h2>Headings</h2> <p> 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 <em>command paragraphs</em> officially. They are paragraphs because they're separated from the rest of the POD by blank lines). </p> <pre>=head1 NAME<br /><br />My::Module - An example module<br /></pre> <p> In WebGUI we use <span>=head1</span> to denote a section of documentation, and <span>=head2</span> to denote subroutines or methods, and <span>=head3</span> to denote subroutine parameters.<br /> </p> </div> <div class="content"> <a name="idNLzyBw380QQ_M3aj02Burg" title="idNLzyBw380QQ_M3aj02Burg"></a> <h2>Basic Formatting</h2> 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.<br /> </div> <a name="id-MmsMzx4rW0JSMmD2BmWig" title="id-MmsMzx4rW0JSMmD2BmWig"></a> <h2>Markup</h2> There are about a dozen markup tags available in POD, but for most purposes only four are important.<br /> <ul><li><span>B<bold text here></span><br /> </li><li>I<italic text here></li><li>C<code text here></li><li>E<gt> <span>(Entities)</span><br /> </li></ul> You can also nest tags like this: B<bold I<and italics> text><br /> <br /> If you need to include a <span>></span> character then you can do one of two things:<br /> <ul><li>C<$foo-E<gt>bar></li><li>C<< $foo->bar >></li></ul> Besides the named entity <span>gt</span>, you can also use decimal entities like <span>E<30></span>.
Keywords