perldoc.pl

An automagic documentation generation program for simple perl scripts

This program is written to make the task of maintaining documentation for
perl programs sipmler. It generates HTML pages from the special #--
characters, as well as producing output lists of the parameters subs
take in, and the return values from a sub.
Usage:
Invoking the program:

> perldoc.pl source output

where souce is the perl source code to be parsed for commenting
and output is the name of the file you wish the HTML to be generated
into.

Commenting syntax:

Lines containing the "#--" sequence (no quotes) are printed directly into
the resulting HTML file, with the following exceptions:

1. Headers: Any line that has a comment, followed by some characters,
   followed by a colon and a newline immediately after the colon, will be
   printed as a header, in bold.
   
2. Null comments: Any line that has the normal sequence followed by a
   second pound sign (that is, pound dash dash pound) in it will not
   be printed. This allows for comments to be removed, and also for the
   "#--" sequence to be used inside your program code (like in this file)
   with minimal annoyance.
   

Subs:
Any subprogram should be followed by perldoc comments listing the
parameters to the program, in order, followed by the return values in
order. An example of this is as follows:

sub Test
#-- Parameter String to be printed
#-- Parameter Some other stuff

{
print shift;
}