Javadoc

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 Smith
 *
 * 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

}

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 Smith
 *
 * 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;
   }
}

Javadoc Tags

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.

 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.

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.

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.