 |
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.
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.
There are about a dozen markup tags available in POD, but for most purposes only four are important.
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:
Besides the named entity gt, you can also use decimal entities like E<30>.
perldoc filename.pm
Keywords: documentation
