CleanCode logo
NAVIGATION: first page in sectionprevious pageup one levelnext pagefinal page in section


Descriptionhierarchical HTML documentation builder for Perl
Platformany Perl-supported (Windows,Linux,...)
Reference API
top level -- click for full size

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.

package level -- click for full size

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.

module level -- click for full size

From the package, one may then select an individual module description, from either the left or right pane. This displays the POD for the module formatted as HTML (indeed, having been run through pod2html). But the POD information has a few enhancements. Regular pod2html generates the table of contents at the top of the file. Pod2HtmlTree, however, adds a quick index if you have multiple variables or multiple public functions within the module, allowing the user to jump directly to any of these. For convenience, the same quick index is added to the beginning of each details section. Pod2HtmlTree further adds the capabilities bar at the top of the page. This shows the languages for which the module is available, along with meta-capabilities of the module: does it have testing support, or a standalone mode, for example. Within the module, then, the capabilities bar indicates whether the equivalent module is also available in Java or JavaScript. Looking to the contents pane, though, or to the package-level summary, there are hyperlinks to the corresponding APIs for those other languages.

This table summarizes the added capabilities of Pod2HtmlTree over pod2html and the similarities to javadoc.

Comparing Capabilities of Documentation Generators
HTML formatyesyesyes
command-line format--yes (perldoc)--
package summaryyes--yes
module summaryyes--yes
master contents paneyes--yes
class hierarchyyes----
uses framesoptional--required
links to other language API----yes
links for runnable tools----yes
Individual Module Capabilities
capabilities bar----yes
method details sectionyesyesyes
method summary sectionyes--quick index

Go to tech docs

Valid XHTML 1.0!Valid CSS!Get CleanCode at Fast, secure and Free Open Source software downloads
Copyright © 2001-2013 Michael Sorens • Contact usPrivacy Policy
Usage governed by Mozilla Public License 1.1 and CleanCode Courtesy License
CleanCode -- The Website for Clean DesignRevised 2013.06.30