There are two kinds of Javadoc comments: class-level comments, and member-level comments. Class-level comments provide the description of the classes, and member-level comments describe the purposes of the members. Both types of comments start with /** and end with */. For example, this is a Javadoc comment:

/** This is a Javadoc comment */

2.1 Class-level Comments

Class-level comments provide a description of the class, and they are placed right above the code that declares the class. Class-level comments generally contain author tags, and a description of the class. An example class-level comment is below:

/**
 * @author Sarah Heckman
 *
 * The Inventory class contains the amounts of all the
 * inventory in the CoffeeMaker system.  The types of 
 * inventory in the system include coffee, milk, sugar
 * and chocolate.
 */
public class Inventory {

   //Inventory code here

}

2.2 Member-level Comments

Member-level comments describe the fields, methods, and constructors. Method and constructor comments may contain tags that describe the parameters of the method. Method comments may also contain return tags. An example of these member-level comments are below:

/**
 * @author Sarah Heckman
 *
 * The Inventory class contains the amounts of all the
 * inventory in the CoffeeMaker system. The types of 
 * inventory in the system include coffee, milk, sugar
 * and chocolate.
 */
public class Inventory { 
   
   /**
    * Inventory for coffee
    */
   private int amtCoffee;

   /**
    * Default constructor for Inventory
    * Sets all ingredients to 15 units
    */
   public Inventory() {
      this.coffee = 15;
   }

   /**
    * Returns the units of coffee in the Inventory
    *
    * @return int
    */
   public int getAmtCoffee() {
      return coffee;
   }

   /**
    * Sets the units of coffee in the Inventory
    *
    * @param int new units coffee
    */
   public void setAmtCoffee(int newCoffee) {
      this.coffee = newCoffee;
   }
}

2.3 Javadoc Tags

2.3.1 To add a class hyperlink, we have to add a tag in the comment. The format of class hyperlink tag is:

{@link <FullClassName> [Display Text]}

FullClassName is the name of the class you wish to link to. The class name must also include the package name if the target class is not in the same package. Display Text is optional. It is the text that will be displayed in the document. If the display text is ignored, the result document will display the full class name.

2.3.2 To add a hyper link to a method of the same class, we use the @link tag like this:

{@link #<MethodSignature> [Display Text]}

MethodSignature is the signature of the target method, including the method name and the parameter types.

Note: It's sometimes difficult to type the right method signature. You may simply type # and some beginning characters of the method name, press Ctrl-SPACE, and a list of the method signatures that match will pop up. You can select a method from the list.

2.3.3 To add a hyper link to a method in a different class, we use the @link tag like this:

{@link <ClassName>#<MethodSignature> [Dsplay Option]}

ClassName is the full name of the class where the method resides. It must include the package name if the class is not in the same package. MethodSignature is the the method signature where this comment links to. If Display Option is not specified, the name of the class and method will be displayed in the document.

Note: Also, you can use Ctrl-SPACE to assist you typing.

2.3.4 The most common Javadoc tags are:

• @author: Describes the author of the document. Used in class-level comments
• @param: Describes a parameter of a method or constructor.
• @return: Describes the return type of a method.
• @throws: Describes an exception a method may throw.
• @exception: Describes an exception.

2.3.5 Some words, like null, true, or false, are better displayed in a fixed-width font. Fixed-width font indicates that the word is used in source code. We can enclose those words in <code></code> segments.

2.3.6 Actually you can use HTML tags in any Javadoc comments. And you have to use special symbols to represent special characters, too. For example, you can use <table><tr><td> in the comments to create a table. Also, you'll need to use &lt; if you want to display <.

Eclipse generates Javadoc everytime you create a class, method, or field, using templates built into the IDE. These templates can be modified to create Javadoc in the format that you want. Or you can turn off the Javadoc generation property.

The Javadoc templates are found by selecting Window > Preferences. Under the tree on the left of the Preferences dialog, open up Java > Code Style > Code Templates.

There is a check box at the bottom of the Code Templates page that says Automatically add comments for new methods and types. If you uncheck this box, Javadoc comments will not be generated.

To configure generated comments, open the Comments tree. Select a type of comment to modify, and select Edit.... Text that looks like ${ } is a variable. Use the Insert Variable... button to see what variables are avaliable to you.