| Previous | Table of Contents | Next |
10.3 DocumentationIn Chapter 3, I showed how you would develop tests for a module, including its documentation. Now I'll show you how to do the documentation itself. Wake up in the back row, there! Yes, I know I said "documentation." That might have conjured up visions of Microsoft PowerPoint presentations, filling in sections with turgid headings like "Functional Requirements" and "Normative References," and formatting signature blocks. I'm not talking about that kind of documentation. I'm talking about documentation that tells another programmer what he or she needs to know about what you have done; the kind of documentation that you want to read when you take over someone else's code. Or the kind of documentation you want to read about your own code when you come back to it a year later and for the life of you can't remember how to use the object class whose interface you thought was "intuitively obvious." 10.3.1 Invasion of the POD PeopleRealizing that documentation is (a) painful and/or boring for programmers to write, and (b) essential for programmers to read, Larry Wall created a system to make it as easy as possible to create documentation. The system is prosaically called Plain Old Documentation (POD). The first convenience of POD is that you can embed it right in the code it's describing; it's just a chunk of text marked off by special lines. You can choose to put the POD anywhere you want; any of the styles shown in Table 10-1 are acceptable and in common usage.
So you can either put the POD all at the beginning, if you think it's the first thing a programmer should see, or all at the end, if you think the code is more important. A small optimization is available to you in the latter case; you can put the POD after a line consisting precisely of the text __END__ and when perl runs your program, it will stop compiling when it sees that line; so even the short time required to recognize and ignore POD will not be used. The last style is "in line," and this is for when you want the documentation for each function to be embedded right next to that function. Obviously you could even carry it further and intersperse POD at smaller granularities, but bear in mind that anything that increases the amount of space a function requires to be viewed in an editor will make the code harder to read. The second convenience is that POD is simple. Larry reasoned that to get people to write documentation, it had to be as easy as possible to create and edit, so there are only a handful of POD formatting directives to remember. You never have to worry about anything in your code being misinterpreted as POD—POD is only recognized between special lines that begin with an equal sign against the left margin and are followed by a word. Within POD you can cause any text to be output verbatim (nothing in it will be interpreted as formatting directives) simply by indenting it. So including POD with code looks as simple as this, for example:
sub quad_roots
{
my ($a, $b, $c) = @_;
my $disc = sqrt($b*$b - 4*$a*$c);
return((-$b + $disc) / 2 / $a, (-$b - $disc) / 2 / $a);
}
=head2 ($root1, $root2) = quad_roots($a, $b, $c);
Return the two roots of a quadratic equation with
the given coefficients, but die if it has imaginary
roots (in which case, use L<Math::Complex>).
Calculated from the classic formula
-b +/- sqrt(b**2 - 4ac)
-----------------------
2a
=cut
POD directive lines need to be between blank lines to be recognized. Within non-verbatim POD text, a few primitive markup tags are recognized. The one I used here, L<>, is used to format its contents as a link; when output to a format that supports the concept of hyperlinking, the text will be linked to the POD page for Math::Complex (assuming the formatter can find it; read on). Just be aware that it will render the output as "the Math::Complex manpage" unless I override the default text for links with something like: use L<Math::Complex|the Math::Complex module>. Remember, POD is for your users to see; notes intended to help maintainance programmers understand that nuances of implementation belong in in-line comments. At the other end of the scale, you might have pure documentation to create (embodying design, perhaps, or requirements, use cases, or customer stories). Go ahead and use POD for that also; there's no law that says it has to be in files that also contain Perl code. 10.3.2 POD FormattersThe main benefit of POD comes from extracting it into a form that contains only documentation. Just as we are used to reading documentation in many formats, POD can be converted to those many formats as well. The Perl core comes with programs for converting POD to text, LaTeX, HTsML, and UNIX troff manual page markup: they're all called pod2something and you'll find them in the directory where your distribution programs are installed, probably the same directory as perl. CPAN contains many more converters; search for "Pod::" in "Modules." For example, Matt Sergeant's pod2xml (http://search.cpan.org/dist/Pod-XML/). |
| Previous | Table of Contents | Next |