Javadoc Comments

Another use for multiline comments is to provide formatted code documentation that can later be used for automated generation of nicely formatted API documentation. These comments are known as javadoc comments, since there is a javadoc tool that will read your source files, look for javadoc comments, and extract them along with other necessary information in order to build documentation web pages. Sun's documentation for the Java APIs themselves was produced using javadoc.

A javadoc comment is a multiline comment. The distinction is that a javadoc comment starts with /** instead of /*. To the javac compiler, there is no difference between the two, since both start with /* and end with */. The javadoc tool understands the difference, however.

Javadoc comments appear directly before the Java element they are documenting. Javadoc comments can appear before fields, but most typically they are used to document classes and methods. There are rules for how a javadoc comment must be formatted in order to be parsed correctly by the javadoc compiler.

The primary reason for producing javadoc web pages is to document your code for external consumption by other project teams or for public distribution. While you can code javadoc comments for every Java element (fields, methods, classes, etc.), you should only expend the time to produce javadoc comments for things you want to expose. Javadoc comments are intended for telling a client developer how to work with a class.

In a team doing test-driven development, Javadoc comments are of lesser value. If done properly, the tests you produce using test-driven development provide far better documentation on the capabilities of a class. Practices such as pair programming and collective code ownership, where developers work on all parts of the system, also minimize the need for producing javadoc comments.

If you code concise, well-named methods, with well-named parameters, the amount of additional text that you should have to write in a Javadoc comment should be minimal. In the absence of text, the Javadoc compiler does a fine job of extracting and presenting the names you chose.

As a brief exercise, provide a Javadoc comment for the CourseSession classthe single-argument constructorand for one of the methods within the class.

Here are the Javadoc comments I came up with:

 package studentinfo; import java.util.*; /**  * Provides a representation of a single-semester  * session of a specific university course.  * @author Administrator  */ class CourseSession {    private ArrayList<Student> students = new ArrayList<Student>();    private Date startDate;    CourseSession() {    }    /**     * Constructs a CourseSession starting on a specific date     *         * @param startDate the date on which the CourseSession begins     */    CourseSession(Date startDate) {       this.startDate = startDate;    }    /**     * @return Date the last date of the course session     */    Date getEndDate() {    ... } 

Take particular note of the @ keywords in the javadoc comments. When you look at the web pages produced by the Javadoc command, it will be apparent what the Javadoc compiler does with the tagged comments. The Javadoc keywords that you will want to use most frequently are @param, to describe a parameter, and @return, to describe what a method returns.

There are lots of rules and many additional @ keywords in Javadoc. Refer to the Javadoc documentation for further information. The Javadoc documentation can be found in the API documentation for the Java SDK (either online or downloaded), under the tool docs for your platform.

Once you've added these or similar comments to your code, go to the command line. (If you are using an IDE, you may be able to generate the documentation from within the IDE.) You will want to create a new empty directory in which to store the generated docs, so that you can easily delete it when you regenerate the Javadoc. Navigate to this empty directory^[10] and enter the following command:

^[10] Instead of navigating to the empty directory, you can also redirect the output from the javadoc command using its -d switch.

 javadoc -package -classpath c:\source;c:\junit3.8.1\junit.jar studentinfo 

The javadoc program will produce a number of .html files and a stylesheet (.css) file. Open the file index.html in a web browser and take a few minutes to see what this simple command has produced (Figure 2.5). Fairly impressive, no?

Figure 2.5. Your Own API Pages

Well, yes and no. I'm embarrassed by the comments I had you put in for the methods. They really added nothing that the code didn't already state. The @param keyword simply restates information that can be gleaned from the parameter type and name. The @return keyword restates information that can be derived from the method name and return type. If you find a need for @return and @param keywords, try to rename the parameters and the method to eliminate this need.

Remove the comments for the constructor and the methods completely, but leave the comment for the classit does provide a bit more value to the reader. Then rerun the javadoc command, bring up the web pages again, and see if you feel any useful information was lost. Your opinion may differ.