CS1027b Computer Science Fundamentals II

Javadoc

Javadoc is a tool to help produce documentation of Java classes and their methods, in the format that we see when viewing the Java API documentation. It is a standard for documenting such things as the author of the code, method parameters, and method return values.

For a complete description of the Javadoc tool, see here . There is far too much detail there for our purposes, but go to the link to Javadoc Reference Pages, and read the section Documentation Comments for more details than are given below.

Javadoc Comments

Javadoc Tags

Javadoc tags are used within the comments, for documenting important aspects of a class or method. Add these tags at the beginning of a line. Here are the most common tags:

Example

/**
 * This class represents a rectangular shape.
 * @author CS1027 Lecture Notes
 */
 
public class Rectangle {
 
/**
 * length of rectangle
 */
  private int length;
/**
 * width of rectangle
 */
  private int width;
 
/**
 * Constructor creates object with given length and width
 * @param len length of rectangle
 * @param wid width of rectangle
 */
  public Rectangle(int len, int wid) {
    length = len;
    width = wid;
  }
/**
 * Accessor method to get length of rectangle
 * @return length of 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
Example:
/**
 *  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. This can be displayed in a browser such as Internet Explorer, with index.html as the starting point.