Pod2HtmlTree

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.

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.