CS1027b Computer Science Fundamentals II

Javadoc is a tool to help produce documentation of Java classes. Javadoc is a standard for documenting the author of the code, method parameters and method return values, classes and instance variables.

• Javadoc reads the comments in Javadoc format in a program and produces HTML-based documentation for the Java classes of that program. HTML-based documentation can be displayed in a Web browser.
• Javadoc automatically links related classes (for example, classes that are used in declarations of variables)

Javadoc Comments

• A Javadoc comment begins with a forward slash followed by two star characters: /** and ends with a start character followed by a forward slash: */.
• A Javadoc comment must appear immediately before the declaration of any class, interface, constructor, method, or field that the comment describes.
• Make sure you put any import statements before the first Javadoc comment.
• Class comments should explain the purpose of the class and who wrote it.
• Method comments should give a brief description of the purpose of the method, what the parameters are, and what is returned. The purpose of the method should be given in one sentence (Javadoc puts this into a summary table).

Javadoc Tags

Javadoc tags are used within the javadoc comments for documenting specific parts of a class or method. These tags must appear at the beginning of a line. Here are the most common Javadoc tags:

• @author used to identify the author of the code
• @param used to describe a parameter for a method (use a separate @param line for each parameter)
• @return used to describe the value returned from a method (used only when return type is not void)

Example

/**
 * This class represents a rectangle. Each rectangle has a specific length and width.
 * @author CS1027 Lecture Notes
 */
 
public class Rectangle {
 
/**
 * Length of the rectangle
 */
  private int length;
/**
 * Width of the rectangle
 */
  private int width;
 
/**
 * Constructor creates a rectangle with the given length and width
 * @param len length of the rectangle
 * @param wid width of the rectangle
 */
  public Rectangle(int len, int wid) {
    length = len;
    width = wid;
  }
/**
 * Accessor method to get the length of the rectangle
 * @return length of the rectangle
 */
  public int getLength() {
    return length;
  }
}

HTML Tags

Since Javadoc outputs HTML-based documentation, you can also put HTML tags within the comments, such as:

<b>text to be displayed</b> in boldface
<p>the beginning of a new paragraph

/**
 *  This is a <b>Javadoc</b> comment.
 */

Running Javadoc

In Eclipse, select Project, Generate Javadoc to create the HTML documentation based on the Javadoc comments of all classes within the project. The HTML documentation can be displayed in a browser such as Internet Explorer; index.html is the starting point of the documentation.