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.
Previous Page
