14.5. Public User Interface—Documenting Classes

One of the most important phases in creating a useful class is providing the user with good documentation describing how the class should be used. This is called the public user interface. Whether a module is object oriented or not, there must be some published user interface—the written documentation—available describing how the programmer (client) should use a class (e.g., what arguments will be passed to a method). The publicly defined interface should not change, even if something in the class is changed. Perl 5 introduced pod commands as a way to document modules. This is done by interspersing the program with POD (Plain Ole Documentation) instructions, similar to embedding HTML or nroff instructions within the text of a file. Then the program is run through a Perl filtering program, which translates the commands into manual pages in a number of different formats.

14.5.1. pod Files

If you look in the standard Perl library, you will find that the modules contain documentation explaining what the module is supposed to do and how to use it. The documentation is either embedded within the program or placed at the end of the program right after the special literal _ _END_ _. This documentation is called POD, short for Plain Ole Documentation. A pod file is just an ASCII text file embedded with special commands that can be translated by one of Perl's special interpreters, pod2html, pod2latex, pod2text, or pod2man. The purpose is to create formatted documents that can be represented in a number of ways. The UNIX man pages are an example of documentation that has been formatted with nroff instructions. It is now easy to embed a set of pod formatting instructions in your scripts to provide documentation in any of the four formats: text, HTML, LaTeX, or nroff.

The first line of the pod documentation starts with an equal sign (=). Each word starting with an equal sign is a formatting instructions for the pod translator. Each formatting instruction must be followed by a blank line.

Example 14.26.

Code View: (Here is the documentation found at the end of the BigFloat.pm module in the standard Perl library, under the subdirectory Math.) =head1 NAME Math::BigFloat - Arbitrary length float math package =head1 SYNOPSIS use Math::BigFloat; $f = Math::BigFloat->new($string); $f->fadd(NSTR) return NSTR addition $f->fsub(NSTR) return NSTR subtraction $f->fmul(NSTR) return NSTR multiplication $f->fdiv(NSTR[,SCALE]) returns NSTR division to SCALE places $f->fneg() return NSTR negation $f->fabs() return NSTR absolute value $f->fcmp(NSTR) return CODE compare undef,<0,=0,>0 $f->fround(SCALE) return NSTR round to SCALE digits $f->ffround(SCALE) return NSTR round at SCALEth place $f->fnorm() return (NSTR) normalize $f->fsqrt([SCALE]) return NSTR sqrt to SCALE places =head1 DESCRIPTION All basic math operations are overloaded if you declare your big floats as $float = new Math::BigFloat "2.123123123123123123123123123123123"; =over 2 =item number format canonical strings have the form /[+-]\d+E[+-]\d+/ . Input values can have inbedded whitespace. =item Error returns 'NaN' An input parameter was "Not a Number" or divide by zero or sqrt of negative number. =item Division is computed to C<max($div_scale,length(dividend)+length(divisor))> digits by default. Also used for default sqrt scale. =back =head1 BUGS The current version of this module is a preliminary version of the real thing that is currently (as of perl5.002) under development. =head1 AUTHOR Mark Biggar =cut Explanation The preceding text is a pod file. It consists of lines starting with an equal sign and a pod command, then a blank line, and text. Perl provides a special translator program that reads the pod file and translates it into a readable file in plain text, HTML format, nroff text, or LaTeX. The next section describes how to use the pod filter programs to make the translation for you.

14.5.2. pod Commands

It's easy to embed pod instructions in a text file. Commands are placed at the beginning of a line, starting with =pod (or any other pod command) and ending with =cut. Everything after the first =pod instruction to the =cut instruction will be ignored by the compiler, just as comments are ignored. The nice thing about using the commands is that they allow you to create bold, italic, or plain text to indent to create headings and more. Table 14.3 contains a list of instructions.

Table 14.3. pod Commands

Paragraph Commands	What They Do
=pod	Marks the start of pod, but an equal sign, followed by any pod instruction starts the documentation
=cut	Marks the end of pod
=head1 heading	Creates a level1 heading
=head2 heading	Creates a level2 heading
=item*	Starts a bulleted list
=over N	Moves over N number of spaces, usually set to 4
=back	Returns indent back to default, no indent
Formatting Commands	What They Do
I<text>	Italic text
B<text>	Bold text
S<text>	Contains text nonbreaking spaces
C<code>	Contains typed text, literal source code
L<name>	Creates a link (cross reference) to name
F<file>	Used for listing filenames
X<index>	An index entry
Z<>	A zero-width character
Filter Specific Commands	What They Do
=for	For HTML-specific commands; e.g., =for html                                                          <IMG SRC=file.gif>                                                          <B>Figure a.>/B>>
	For text-specific commands; e.g., =for text text to represent what the above image means
	For manpage-specific commands; e.g., =for man                                                            .ce 3                                                            <center next three lines>

14.5.3. How to Use the pod Interpreters

The pod interpreters come with the Perl distribution and are located in the bin directory under the main Perl directory; for example, in /usr/bin/perl5/bin.

The four interpreters are

pod2html	(translate to HTML)
pod2text	(translate to plain text)
pod2man	(translate to nroff, like UNIX man pages)
pod2latex	(translate to LaTeX)

The easiest way to use the interpreters is to copy the one you want into your own directory. For example:

$ cp /usr/bin/perl5/bin/pod2text

You may also copy the library routine into your directory:

$ cp /usr/bin/perl5/lib/BigFloat.pm

Now when you list the contents of the directory, you should have both the pod interpreter and the library module.

$ ls
BigFloat.pm
pod2text

14.5.4. Translating pod Documentation into Text

The easiest way to translate the pod commands to text for your terminal screen is to use the perldoc command that comes with the Perl distribution. It may not be in your search path, but it is usually found in the bin directory under perl. The following command would display all the documentation for the BigFloat.pm module.

    perldoc Math::BigFloat

Another way to translate pod directives to text is to let the pod interpreter filter through the module and create an output file to save the translated text. If you don't redirect the output to a file, it will simply go to the screen.

$ pod2text BigFloat.pm > BigFloat.Text
$ cat BigFloat.Text  (The output file after pod commands have been
                      translated into text.)

NAME
    Math::BigFloat - Arbitrary length float math package

SYNOPSIS
      use Math::BogFloat;
      $f = Math::BigFloat->new($string);

      $f->fadd(NSTR) return NSTR              addition
      $f->fsub(NSTR) return NSTR              subtraction
      $f->fmul(NSTR) return NSTR              multiplication
      $f->fdiv(NSTR[,SCALE])   returns NSTR   division to SCALE places
      $f->fneg() return NSTR                  negation
      $f->fabs() return NSTR                  absolute value
      $f->fcmp(NSTR) return CODE              compare undef,<0,=0,>0
      $f->fround(SCALE) return NSTR           round to SCALE digits
      $f->ffround(SCALE) return NSTR          round at SCALEth place
      $f->fnorm() return (NSTR)               normalize
      $f->fsqrt([SCALE]) return NSTR          sqrt to SCALE places

DESCRIPTION
    All basic math operations are overloaded if you declare your big floats as

$float=newMath::BigFloat"2.123123123123123123123123123123123";

     number format
     canonical strings have the form /[+-]\d+E[+-]\d+/ . Input
     values can have inbedded whitespace.

Error returns 'NaN'
     An input parameter was "Not a Number" or divide by zero or
     sqrt of negative number.

Division is computed to
     `max($div_scale,length(dividend)+length(divisor))' digits by
     default. Also used for default sqrt scale.
BUGS
    The current version of this module is a preliminary version of
    the real thing that is currently (as of perl5.002) under
    development.

AUTHOR
    Mark Biggar

					  

14.5.5. Translating pod Documentation into HTML

To create an HTML document, copy pod2html into your directory and type

$ pod2html BigFloat.pm > BigFloat.pm.html

The pod2html translator will create a file called BigFloat.pm.html. Now open your browser window and assign BigFloat.pm.html to a file protocol in the URL location box; e.g., <file:/yourdirectory path/BigFloat.pm.html>.^[9]

^[9] If you receive some obscure diagnostic messages, it may be that the documentation for the .pm file contains links to some other page that cannot be resolved by the pod filter.