Login | Register   
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

Doclets: Decipher and Document Java Code Easily : Page 3

Developers are increasingly required to take over and maintain multiple projects. Doclets, a new addition to Java SE 6, provides a mechanism for learning the source code of Java projects with relative ease.


advertisement
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.



Raghu Donepudi, an independent contractor, currently is a technical manager for a federal government agency. He has a master's degree in Computer Science from Lamar University in Texas. He is a Sun-certified Java developer and the author of many software design techniques.
Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap