How to put comments in your code with Javadoc

One of the nice things about Java is javadoc. The javadoc utility lets you put your comments right next to your code, inside your ".java" source files. When you're satisfied with your code and comments, you simply run the javadoc command, and your HTML-style documentation is automatically created for you.

A great thing about keeping your comments right next to your code is that it's much easier to keep the code and the documentation in sync. When you change the code, you change the comments, and run javadoc again. Very simple, very clean.

A working example

The code shown below provides a good example of what Javadoc comments look like. Forget for a while what this Java code is doing (it's not doing much anyway), and focus on the comments.

The first thing to notice is that javadoc comments begin with the /** symbol, and end with the */ symbol. This is a little bit different than the standard C or C++ style comments you might be used to seeing.

/**  
* Porsche.java - a simple class for demonstrating the use of javadoc comments.  
* @author  Alvin Alexander
* @version 1.0 
* @see Automobile
*/ 
public class Porsche extends Automobile {  

   protected String color; 

   /**  
    * Retrieve the value of color.  
    * @return A String data type.  
    */  
   public String getColor() {  
      return color;  
   } 

   /**  
    * Set the value of color.  
    * @param newColor A variable of type String.  
    */  
   public void setColor(String newColor) {  
      color = newColor;  
   }  
}  

As you can see from the listing, javadoc also lets you define certain tags within your javadoc comments. Using these tags causes javadoc to create additional (and better) documentation on your behalf.

The table below briefly describes the purpose of the javadoc tags used in the sample source code shown above:

@author	This tag lets you put the name of the code author into the documentation.
@parameter	This tag is used to define parameters that are passed into a method.
@return	This tag defines values that are returned from methods.
@see	This tag creates "See Also:" output. You'll normally use this tag to refer to related classes.
@version	This tag lets you define the version of the Java code you're developing. For instance, the code displayed in Listing 1 is considered to version 1.0.

This table shows the most commonly-used Javadoc tags.

How it works

There are only a few rules to worry about with javadoc. Keep these in mind when creating javadoc documentation in your code:

• Javadoc comments only have meaning when they appear before a public class, or before public or protected variables and methods.
• The first line in a javadoc comment is a summary line. You'll see this description at the top of the HTML file for the class (i.e., Porsche.html), and also in the AllNames.html file.

Also note that there is no need to begin each line of comments with an asterisk, as we've shown above. This is just a convention among many programmers, but not a standard. If you don't like this convention, just begin the comment with the /** characters, and end them with the */ characters.

Generating your Javadoc

After you've created your code, just run the javadoc command on your ".java" file, like this:

javadoc Porsche.java

When you do this, javadoc generates documentation in HTML format for all of your public classes, and your public and protected methods and variables. Based on the files you submit and the documentation within those files, javadoc creates four types of HTML files, as shown below:

packages.html	A listing of each package you generated documentation for, and the classes they contain. In a small example like ours, this file won't contain any really useful information.
AllNames.html	This file contains an alphabetical index of all the variables (also referred to as fields) and methods you've defined.
tree.html	A listing of all the classes you've generated documentation for, and where those classes fit in the class hierarchy.
Porsche.html	There will be one file of this type for each class defined. This file contains the actual documentation for the class.

This table provides brief descriptions of the files created when the javadoc command is run on your Java source files.

The output javadoc documentation

Well, that's enough about how it works. The best way to show how javadoc really works is to show the output it generates. Follow the links below to see the various output documentation files that javadoc created for the simple Porsche.java file shown earlier.

• Porsche.html
• AllNames.html
• tree.html
• packages.html

I think you'll agree with me after seeing the documentation that javadoc creates that it sure is a lot easier to let javadoc do the hard work. Think of the benefits:

• The documentation sits right next to the code. Change the code, and it's easy to change the documentation.
• Four different documentation file types are created for you. These are really needed with object-oriented programming.
• The four different file types are all cross-linked, so clicking on a link in one file takes you directly to documentation in another file. Can you imagine doing this manually?