Automated SDK JavaDoc Documentation Part Deux

A little touch of XSLT magik

In a prior posting, I talked about the pain point of creating SDK JavaDoc Help content for eclipse. It tends to get out of synch with the actual documentation, as the TOC.xml has to be maintained manually. I found a DocLet called JELDoclet that creates one or more XML files for the javadoc. With this created, one can do a little bit of XSLT to do the following:

1. Create the HTML documentation for the class and package files, that are normally produced by the standard javadoc.
2. Create the necessary Toc.xml file, that is used by the eclipse help system.

To integrate the help nicely into eclipse, it is usually handy to have everything grouped by Package, and then the documentation for each class underneath the package it belongs too. All of this information is available from the JEL xml file, but the trick with XSLT 1.0, is that it doesn't have a grouping statement. Why not just use XSLT 2.0? The main reason is that the base XSLT parser that comes with Java 1.5 JDK is Xalan based. Sun repackaged and only included portions of the full Xalan, mainly they use the XSLTC compiler/interpreter from Xalan. Anyways, I wanted to keep this to the lowest common denominator.

Since XSLT 1.0 doesn't include a group-by statement, and the Meunchian Grouping method can be confusing, I found this little piece of EXSLT magik by Oleg Tkachenko. Basically the code simulates a group-by clause. Here is the xslt that generates the toc.xml from the JEL xml file:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:set="http://exslt.org/sets"
xmlns:xalan="http://xml.apache.org/xalan"
 exclude-result-prefixes="set"
>
<xsl:param name="sdkname">Some Name</xsl:param>
<xsl:param name="dir">doc/html</xsl:param>
<xsl:output indent="yes" encoding="UTF-8" xalan:indent-amount="3"/>
<xsl:key name="allPackages" match="jelclass" use="@package"/>

<xsl:template match="/jel">
   <toc label="{$sdkname}">
      <topic label="Reference">
         <xsl:for-each select="set:distinct(jelclass/@package)">
            <topic label="{.}">
               <xsl:apply-templates select="key('allPackages', .)"/>
            </topic>
         </xsl:for-each>
      </topic>
   </toc>
</xsl:template>

<xsl:template match="jelclass">
   <topic label="{@fulltype}" href="{$dir}/{@fulltype}.html"/>
</xsl:template>

</xsl:stylesheet>

Basically, the code reads the JEL xml file that contains all the java classes and their documentation, and groups all the packages together, it then processes each package and creates the necessary topic entries for each class in the toc.xml file.

The above xslt runs on Xalan, and should run on the Sun version of Xalan as well. The javadoc doclet steps, the html generation, and the toc.xml generation steps can be included in an Ant build script. This allows for the SDK JavaDoc Documentation to be generated automatically everytime a build is done. If a new class or package is included, that new class and it's corresponding documentation will be included as well. The same options that you have for the standard javadoc, are available with the jeldoclet, so you have the same level of control on what gets included and what doesn't.

No More Excuse for Outdated Documentation

[pulls out the soapbox]

Bug 231472 contains most of the work, except for the xslt above, but I'll get that added in a few days. As committers, it's our responsibility to the community to make sure they have the appropriate documentation. Not only so that they know how to use the classes we have created, but also for those people that need to come behind us and maintain the code that we provide. A couple of additional items that would be nice to do (PDE adds some checks to do some of these).

1. Make sure all your classes both internal and public API have appropriate javadoc documentation.
2. Automate the generation and upkeep of that documentation.
3. Follow the JavaDoc best practices (Something that we in the XSL Tools project need to correct).
4. Run the JavaDoc DocCheck doclet against your java source. It will provide a nice report telling you what is missing in the way of javadoc documentation.

I know that we are all busy, and writing documentation isn't the thing we enjoy doing, but it makes the user communities job easier. I personally don't believe that JavaDoc is something that the user community should write. It's something that we need to make sure we do consistently. We need to make sure that we make the time to do what is right for the community as a whole.