|N U T S H E L L|
|Description||hierarchical HTML documentation builder for Perl|
|Platform||any Perl-supported (Windows,Linux,...)|
Perl aficionados are aware of Perl's built-in documentation capabilities, wherein one may place documentation "source code" right next to the code it is documenting, making maintenance easier. One may then use perldoc to generate command-line documentation, or pod2html to create an HTML version. Javadoc for Java code is similar, but rather than using yet another language like POD, Java uses pure HTML as its documentation language. Javadoc has the added capability of being able to generate not just documentation for a module but a hierarchical, hyperlinked documentation tree of your entire library.
Do I sound envious from the Perl perspective? Well Pod2HtmlTree bridges the gap. Like javadoc, and leveraging pod2html, Pod2HtmlTree generates an interconnected hyperlinked documentation tree. The first illustration shows the top level of the hierarchy. (Click on the illustration to load the full size screen shot.) The left pane contains a list of all packages and modules; the right pane contains a brief description of each package. One may select a package from either pane, or go directly to a module from the left pane.
The next illustration shows a package-level view (again, click on the illustration to see an enlargement). The left navigator pane does not change, but notice the right pane now lists a brief description of each module within the package, along with other introductory text for the package. This allows you to "drill down" to find what you are looking for. Both the top-level summary list above and this package-level summary list, plus the master package/module list are generated automatically by Pod2HtmlTree, but that does not mean it is without effort on your part. Each module must include not just proper POD documentation, but follow more stringent guidelines for information to be picked up and scanned properly by Pod2HtmlTree.
This table summarizes the added capabilities of Pod2HtmlTree over pod2html and the similarities to javadoc.
|command-line format||--||yes (perldoc)||--|
|master contents pane||yes||--||yes|
|links to other language API||--||--||yes|
|links for runnable tools||--||--||yes|
|Individual Module Capabilities|
|method details section||yes||yes||yes|
|method summary section||yes||--||quick index|