What Is XDoclet?

When teaching new computer science students, one of the most important issues in software development I try to get across is the need to document the code. There must be some defect in the documentation gene when software engineers are created, because no matter how hard this topic is pounded, nobody seems to get it right. In an attempt to help with the defective gene, Java architects chose to provide the technology of self-documenting code within the language itself and provide the tools for building much of the needed documentation. This technology is called Javadoc , and we need to explore it before looking at XDoclet. Of course, no code is self-documenting without the software engineer providing the necessary tags within the code, but that's another story.

Javadoc is a technology in which defined attributes are placed in comment blocks of the code in order to provide a processor application with information about the code itself. Consider this example:

 /**  * The JavaHelpMe class has been documented   * using multiple lines of comments  */ public class JavaHelpMe { } 

Here we have a simple class with a comment block used to describe the class. All of the text between the beginning /* and the closing / symbols will be ignored by the Java compiler and left for the reader of the code or Javadoc. The comment blocks can be found on many of the language constructs, as we see here:

 /**  * The JavaHelpMe class has been documented   * using multiple lines of comments  */ public class JavaHelpMe {   /** a method comment */    public int returnHelpO {   } } 

Of course, these comments blocks arent anything new because we used the same type of construct when we wrote our C code; at least we were suppose to comment that code. The Javadoc technology adds to the comment blocks using tags and tag descriptions. For example:

 /**  * The JavaHelpMe class has been documented   * using multiple lines of comments  * @see com.my.class  */ public class JavaHelpMe {   /** a method comment     *  @return int value    */    public int returnHelpO {   } } 

In this example, we've added two Javadoc tags, @see and @return. Each of these tags will be processed by Javadoc and specific actions taken when encountered . In the case of the @see, additional output will be added to the description of the class like this:

 See Also: class 

where class is a link to another Javadoc page.

There are countless more Javadoc tags that can be found at http://java.sun.com/j2se/javadoc/. By using the Javadoc tags, the code can basically self-document as long as the developer uses the tags and provides comment blocks. So, getting to our point of this section, XDoclet is a technology that uses tags in the same manner as Javadoc, but instead of producing help files, the XDoclet system produces code.