Saturday, October 17, 2009

Work in Progress: an Open DocCheck replacement

While it is still very much in progress, I have already made more progress than I had hoped for. The JavaDoc Doclet API is actually not too difficult to use, though my use will very likely improve more later. The CDK has been using Sun's DocCheck utility for testing the library's JavaDoc quality, but the reports never really satisfied me. Moreover, the most recent version is ancient and because it is closed source, no one can continue on those efforts. DocCheck is MIA.

Instead, PMD is given nice overviews of what it believes to be wrong with the CDK, and also provides a decent XML format which allows extraction of information, which is used by, for example, SuperNightly as showed yesterday in PMD 2.4.5 installed in the CDK 1.2.x branch.

I have been pondering about it for a long time now, but writing a JavaDoc checking library is hardly core cheminformatics research; at least, you would not get funding for it, despite everyone always complaining about good documentation. Alas.

Last week, I was reviewing some more code, and again saw the very common error of the missing period at the end of the first sentence in JavaDoc. This one is sort of important for proper JavaDoc documentation generation, but the complexity of the current DocCheck reporting, people are not familiar enough with it. Being tired of having to repeat myself, I decided to address the problen, but creating better Nightly error reporting for the CDK JavaDoc.

So, I started OpenJavaDocCheck, or ojdcheck. As mentioned, I have made quite promising progress, and the current version provides the ability to write custom tests (which I plan to use for validating content of CDK taglet content), and create XML as well as XHTML which can be saved to any file. To give you a glimps of where things are going, here's a screenshot of the current XHTML output:

The current list of tests is really small, and consists of a single test:
  • test if each class and method has JavaDoc