Section 11.7. Javadoc Comments

[Page 367 (continued)]

11.7. Javadoc Comments

We have only used comments to highlight the different parts of a class definition: fields, constructors, and methods. You should add Javadoc comments to your class definition. Javadoc is a utility from Sun that allows you to create HTML (Hyper-Text Markup Language) documentation from special Javadoc comments in your source code. Comments make it easier to figure out what a class is for and what is happening in it.

You might think that you don't need to comment a class if you are the only one using it, but the point of creating a class is to make reusable pieces. Comments are notes in plain language that will help you and others understand and reuse the class. All of the classes that are part of the Java language have Javadoc comments in them. The API documentation was created by running the Javadoc utility on the source files.

11.7.1. Class Comment

You should add a comment just before the class definition to explain the class and to give the author's name. Javadoc comments start with '/**' and end with '*/'. They can take up several lines. Here is an example of a class comment:

/**  * Class that describes a student. A student has a name and an  * array of grades. You can get information about a student  * such as her/his name and grade average. 
[Page 368] *  * @author Barb Ericson  */ public class Student

Notice that the Javadoc comment is just before the class declaration. It tells something about the purpose of the class. It also should tell who the author or authors are. If there is more than one author you just add another '@author' tag. The '@author' tag is just one of many special tags defined in Javadoc that will pull particular information out of the source code and format it in the HTML documentation.

11.7.2. Method Comments

You should add a comment before each method. This comment should describe the purpose of the method, any parameters to the method, and what is returned from the method (if anything). Here is an example of a method comment:

/**  * Method to set a grade in the grade array  * @param index the index to set the grade at  * @param newGrade the new grade to use  * @return true if success, else false  */ public boolean setGrade(int index, double newGrade) {

Notice that it has two '@param' tags because it has two parameters. Also notice that it has a '@return' tag since it returns a value. Here is another method comment:

/**  * Method to return the average of the grades for this student  * @return the average of the grades or 0.0 if no grade array  * or no grades  */ public double getAverage()

Notice that this one doesn't have any '@param' tags in it. This is because it doesn't have any parameters. It does have the '@return' tag in it because it does return a value.

11.7.3. Constructor Comments

You can add Javadoc comments to constructors as well. They look like method comments. Of course you won't need any '@return' tags since constructors do not return a value.

11.7.4. Generating the Documentation

Once you add Javadoc comments to your class you can generate HTML documentation in DrJava by clicking on the JAVADOC button. This will generate all the HTML documentation for all classes that are in the same directory as all the open files. This is how the API for Java 1.5 (5.0) (http://java.sun.com/j2se/1.5.0/docs/api/) was created. You can see the API for Java 1.4.2 at http://java.sun.com/j2se/1.4.2/docs/api/.

---

[Page 369]

You can also see a preview of the HTML documentation for just the current class by clicking TOOLS and then on PREVIEW JAVADOC FOR CURRENT DOCUMENT (Figure 11.15). This can be useful to check what the documentation looks like so far. It will also show you where you need to add documentation.

Figure 11.15. Showing the HTML documentation generated from Javadoc comments.

If you aren't using DrJava you can create the HTML documentation using the Javadoc utility that comes with Java. You can open a command prompt and go to the directory with the Java source in it and then type javadoc *.java to create the documentation for all the source files in the directory. To create the documentation for just the Student class use javadoc Student.java.