rying to understand the logic of an unfamiliar Java project can be taxing. Learning the project’s code is even more difficult when there is no knowledge transfer from the developer(s) who developed it. Increasingly, this is becoming a common task for developers, which isn’t necessarily bad news because it provides a great opportunity for job security. A developer becomes indispensable when he or she is the knowledge source for existing projects.

Doclets, a new addition to Java SE 6, is very handy for reviewing existing source code and mastering the logic behind it. Doclet is a starting class for defining the entry point methods of the package com.sun.javadoc. The Doclet API is an extension for Javadoc, the original Java tool that automatically creates documentation from source code files. The Doclet API provides various features for customizing documentation output and offers architectural means for embedding the crux of source code logic for new projects inside custom tags—the proper way to document logic. This enables future developers to simply review the custom tags documentation to understand the logic instead of scouring through the entire documentation.

The predecessor to Doclets—Javadoc—has been around since Java came out, but it offered developers no control over the output it generated nor did it provide customization features. Javadoc specifies a fixed set of tags that developers can use to document code logic and generates boilerplate documentation in HTML. It also requires the developer to keep all code comments up to date—an easy task to forget. If the code is missing all the Javadoc-specified tags—a common scenario because in tight development schedules documenting the code takes the lowest priority, refactoring the program requires as much time as reading the code itself.

Comparing the old with the new:

• Javadoc merely looks for tags to generate documentation; Doclets compile the source files before generating the documentation.
• Doclets stop processing if they encounter any errors at compile time; Javadoc lets you generate documentation for un-compiled code.

Another documentation tool, Classdoc, is an open source project for generating documentation for missing source files from compiled code. However, it has its own limitations:

• It is limited in displaying inner classes.
• It doesn’t provide hyperlinks.
• It provides only the signatures of methods, so developers must use a decompiler to understand the code in Classdoc output.

This article introduces the main classes and methods to get started with Doclets and demonstrates its features with practical examples.

Doclets in Depth
A simple Doclet can scan through all classes and print only the fields, methods, and super class information—very handy for segregating the main logic-processing classes from the support classes. To make a developer’s life even easier, the Doclet API’s Doc class has methods to retrieve the position of a particular line in a given file.

MyDoclet.java in the source code download is an example of a simple Doclet. It walks through each class and prints all the methods and their method signatures. However, the Doclet API provides various additional classes and methods to customize processing further. All custom Doclets, such as those included in the source code download, must extend from com.sun.javadoc.Doclet and implement the following start method:

public static boolean start(RootDoc root)

Figure 1. Output from Running Doclet Example: The –private option processes the private methods of the class, while the –Doclet option forces Javadoc to use the example Doclet.

The root.classes() method of RootDoc grants access to an array of ClassDocs, which in turn could be used to navigate the class structures (for example, methods, constructors, fields, etc.). The typeParamTags() method of the ClassDoc or MethodDoc interfaces retrieves all the existing parameter tags documented in the code. The MethodDoc.tags(String tagName) method allows you to retrieve your custom tags by passing a custom tag name.

Run the Doclets
To run the Doclets in the source code download, take the following steps:

1. Include tools.jar in your classpath.
2. In the command prompt, type the following commands:

   $>javadoc -private -doclet MyDocletMissingDocumentation -docletpath . TestNoDocumentation.java

The –private option processes the private methods of the class. The –Doclet option forces Javadoc to use your Doclet as opposed to the standard Doclet. Figure 1 shows the output.

Architectural Usage
The Doclet API comes in very handy for peer code reviews as well. Peer reviewers could write a custom Doclet, and prior to reviewing the code, they could run it on existing projects to ensure that the code is properly documented with all the comment tags. This saves the coders and reviewers a lot of time.

Figure 2. The Output from Test.java: Even though other tags are present in Test.java, only the documentation related to custom tags is retrieved.

MyDocletCustomTag.java in the source code download demonstrates how you can define the documentation of special logic in custom tags and how a custom Doclet can print out only the classes and methods that have these custom tags. For example, here is the output from Test.java, a sample file that is run through MyDocletCustomTag.java:

	/**	 * @myTag getAge() returns 2 years less for women	 * @myTag getAge() returns actual age for men	 */

Even though other tags are present in Test.java, only the documentation related to custom tags is retrieved (see Figure 2).

Figure 3. The Output from PeerReviewDoclet.java: PeerReviewDoclet.java lists all the methods that are missing documentation, methods that have empty tags, and methods that have duplicate tags.

Another Doclet example, PeerReviewDoclet.java, lists all the methods that are missing documentation, methods that have empty tags, and methods that have duplicate tags (see Figure 3).

The PeerReviewDoclet.java Doclet could be enhanced to look for unnecessary documentation, multiple tags, and so on, and basically to automate the entire peer-review process. For well-defined software development lifecycles, use cases could be tied to code documentation using custom tags.

Doclets Needed Now More Than Ever
With all the IT outsourcing today, code written in one country often is maintained by people in other countries. As such, documentation is no longer an option, but rather a requirement. In response, various Doclet support tools are available to make documentation generation more accessible. For example, MIF Doclet output documentation in PDF format and XDoclets generate code based on tag information.