Java Documentation Comments (Java in a Nutshell)

7.3. Java Documentation Comments

Most ordinary comments within Java code explain the implementation details of that code. In contrast, the Java language specification defines a special type of comment known as a doc comment that serves to document the API of your code. A doc comment is an ordinary multiline comment that begins with /** (instead of the usual /*) and ends with */. A doc comment appears immediately before a class, interface, method, or field definition and contains documentation for that class, interface, method, or field. The documentation can include simple HTML formatting tags and other special keywords that provide additional information. Doc comments are ignored by the compiler, but they can be extracted and automatically turned into online HTML documentation by the javadoc program. (See Chapter 8, "Java Development Tools", for more information about javadoc.) Here is an example class that contains appropriate doc comments:

/**
 * This immutable class represents <i>complex
 * numbers</i>. 
 *
 * @author David Flanagan
 * @version 1.0
 */
public class Complex {
  /**
   * Holds the real part of this complex number. 
   * @see #y
   */
  protected double x;

  /**
   * Holds the imaginary part of this complex number. 
   * @see #x
   */
  protected double y;

  /**
   * Creates a new Complex object that represents the complex number
   * x+yi. 
   * @param x The real part of the complex number. 
   * @param y The imaginary part of the complex number. 
   */
  public Complex(double x, double y) {
    this.x = x;
    this.y = y;
  }

  /**
   * Adds two Complex objects and produces a third object that represents
   * their sum. * @param c1 A Complex object
   * @param c2 Another Complex object
   * @return  A new Complex object that represents the sum of 
   *          <code>c1</code> and
   * <code>c2</code>. 
   * @exception java.lang.NullPointerException 
   *            If either argument is <code>null</code>. 
   */
  public Complex add(Complex c1, Complex c2) {
    return new Complex(c1.x + c2.x, c1.y + c2.y);
  }
}

7.3.1. Structure of a Doc Comment

The body of a doc comment should begin with a one-sentence summary of the class, interface, method, or field being documented. This sentence may be displayed by itself, as summary documentation, so it should be written to stand on its own. The initial sentence can be followed by any number of other sentences and paragraphs that describe the class, interface, method, or field.

After the descriptive paragraphs, a doc comment can contain any number of other paragraphs, each of which begins with a special doc-comment tag, such as @author, @param, or @returns. These tagged paragraphs provide specific information about the class, interface, method, or field that the javadoc program displays in a standard way. The full set of doc-comment tags is listed in the next section.

The descriptive material in a doc comment can contain simple HTML markup tags, such as such as <I> for emphasis, <CODE> for class, method, and field names, and <PRE> for multiline code examples. It can also contain <P> tags to break the description into separate paragraphs and <UL>, <LI>, and related tags to display bulleted lists and similar structures. Remember, however, that the material you write is embedded within a larger, more complex HTML document. For this reason, doc comments should not contain major structural HTML tags, such as <H2> or <HR>, that might interfere with the structure of the larger document.

Avoid the use of the <A> tag to include hyperlinks or cross references in your doc comments. Instead, use the special {@link} doc-comment tag, which, unlike the other doc-comment tags, can appear anywhere within a doc comment. As described in the next section, the {@link} tag allows you to specify hyperlinks to other classes, interfaces, methods, and fields without knowing the HTML-structuring conventions and filenames used by javadoc.

If you want to include an image in a doc comment, place the image file in a doc-files subdirectory of the source code directory. Give the image the same name as the class, with an integer suffix. For example, the second image that appears in the doc comment for a class named Circle can be included with this HTML tag:

<IMG src="doc-files/Circle-2.gif">

Because the lines of a doc comment are embedded within a Java comment, any leading spaces and asterisks (*) are stripped from each line of the comment before processing. Thus, you don't need to worry about the asterisks appearing in the generated documentation or about the indentation of the comment affecting the indentation of code examples included within the comment with a <PRE> tag.

7.3.2. Doc-Comment Tags

As I mentioned earlier, javadoc recognizes a number of special tags, each of which begins with an @ character. These doc-comment tags allow you to encode specific information into your comments in a standardized way, and they allow javadoc to choose the appropriate output format for that information. For example, the @param tag lets you specify the name and meaning of a single parameter for a method. javadoc can extract this information and display it using an HTML <DL> list, an HTML <TABLE>, or however it sees fit.

The doc-comment tags recognized by javadoc are the following; a doc comment should typically use these tags in the order listed here:

@author name

Adds an "Author:" entry that contains the specified name. This tag should be used for every class or interface definition, but must not be used for individual methods and fields. If a class has multiple authors, use multiple @author tags on adjacent lines. For example:

@author David Flanagan
@author Paula Ferguson

List the authors in chronological order, with the original author first. If the author is unknown, you can use "unascribed". javadoc does not output authorship information unless the -author command-line argument is specified.

@version text

Inserts a "Version:" entry that contains the specified text. For example:

@version 1.32, 08/26/99

This tag should be included in every class and interface doc comment, but cannot be used for individual methods and fields. This tag is often used in conjunction with the automated version-numbering capabilities of a version-control system, such as SCCS, RCS, or CVS. javadoc does not output version information in its generated documentation unless the -version command-line argument is specified.

@param parameter-name description

Adds the specified parameter and its description to the "Parameters:" section of the current method. The doc comment for a method or constructor must contain one @param tag for each parameter the method expects. These tags should appear in the same order as the parameters specified by the method. The tag cannot be used in class, interface, or field doc comments. You are encouraged to use phrases and sentence fragments where possible, to keep the descriptions brief. However, if a parameter requires detailed documentation, the description can wrap onto multiple lines and include as much text as necessary. You can also use spaces to align the descriptions with each other. For example:

@param o      the object to insert
@param index  the position to insert it at

@return description

Inserts a "Returns:" section that contains the specified description. This tag should appear in every doc comment for a method, unless the method returns void or is a constructor. The tag must not appear in class, interface, or field doc comments. The description can be as long as necessary, but consider using a sentence fragment to keep it short. For example:

@return <code>true</code> if the insertion is successful, or
        <code>false</code> if the list already contains the
        specified object.

@exception full-classname description

Adds a "Throws:" entry that contains the specified exception name and description. A doc comment for a method or constructor should contain an @exception tag for every checked exception that appears in its throws clause. For example:

@exception java.io.FileNotFoundException 
           If the specified file could not be found

The @exception tag can optionally be used to document unchecked exceptions (i.e., subclasses of RuntimeException) the method may throw, when these are exceptions that a user of the method may reasonably want to catch. If a method can throw more than one exception, use multiple @exception tags on adjacent lines and list the exceptions in alphabetical order. The description can be as short or as long as necessary to describe the significance of the exception. This doc-comment tag cannot be used in class, interface, or field comments. The @throws tag is a synonym for @exception.

@throws full-classname description

This tag is a synonym for @exception. It was introduced in Java 1.2.

@see reference

Adds a "See Also:" entry that contains the specified reference. This tag can appear in any kind of doc comment. reference can take three different forms. If it begins with a quote character, it is taken to be the name of a book or some other printed resource and is displayed as is. If reference begins with a < character, it is taken to be an arbitrary HTML hyperlink that uses the <A> tag and the hyperlink is inserted into the output documentation as is. This form of the @see tag can insert links to other online documents, such as a programmer's guide or user's manual.

If reference is not a quoted string or a hyperlink, the @see tag is expected to have the following form:

@see feature label

In this case, javadoc outputs the text specified by label and encodes it as a hyperlink to the specified feature. If label is omitted (as it usually is), javadoc uses the name of the specified feature instead.

feature can refer to a package, class, interface, method, constructor, or field, using one of the following forms:

pkgname

A reference to the named package. For example:

@see java.lang.reflect

pkgname.classname

A reference to a class or interface specified with its full package name. For example:

@see java.util.List

classname

A reference to a class or interface specified without its package name. For example:

@see List

javadoc resolves this reference by searching the current package and the list of imported classes for a class with this name.

classname#methodname

A reference to a named method or constructor within the specified class. For example:

@see java.io.InputStream#reset
@see InputStream#close

If the class is specified without its package name, it is resolved as described for classname. This syntax is ambiguous if the method is overloaded or the class defines a field by the same name.

classname#methodname(paramtypes)

A reference to a method or constructor with the type of its parameters explicitly specified. This form of the @see tag is useful when cross-referencing an overloaded method. For example:

@see InputStream#read(byte[], int, int)

#methodname

A reference to a non-overloaded method or constructor in the current class or interface or one of the containing classes, superclasses, or superinterfaces of the current class or interface. Use this concise form to refer to other methods in the same class. For example:

@see #setBackgroundColor

#methodname(paramtypes)

A reference to a method or constructor in the current class or interface or one of its superclasses or containing classes. This form works with overloaded methods because it lists the types of the method parameters explicitly. For example:

@see #setPosition(int, int)

classname#fieldname

A reference to a named field within the specified class. For example:

@see java.io.BufferedInputStream#buf

If the class is specified without its package name, it is resolved as described for classname.

#fieldname

A reference to a field in the current class or interface or one of the containing classes, superclasses, or superinterfaces of the current class or interface. For example:

@see #x

{@link reference}

The @link tag is like the @see tag except that, instead of placing a link to the specified reference in a special "See Also:" section, it inserts the link inline. A @link tag can appear anywhere that HTML text appears in a doc comment. In other words, it can appear in the initial description of the class, interface, method, or field and in the descriptions associated with the @param, @returns, @exception, and @deprecated tags. Because the @link tag can appear within arbitrary HTML text, the curly braces are required to delimit it. The reference for the @link tag uses the same syntax as the @see tag documented previously. For example:

@param regexp The regular expression to search for. This string
              argument must follow the syntax rules described for
              {@link RegExpParser}.

@deprecated explanation

As of Java 1.1, this tag specifies that the following class, interface, method, or field has been deprecated and that its use should be avoided. javadoc adds a prominent "Deprecated" entry to the documentation and includes the specified explanation text. This text should specify when the class or member was deprecated, and, if possible, suggest a replacement class or member and include a link to it. For example:

@deprecated As of Version 3.0, this method is replaced
            by {@link #setColor}.

Although the Java compiler ignores all comments, it does take note of the @deprecated tag in doc comments. When this tag appears, the compiler notes the deprecation in the class file it produces. This allows it to issue warnings for other classes that rely on the deprecated feature.

@since version

Used to specify when the class, interface, method, or field was added to the API. It should be followed by a version number or other version specification. For example:

@since JNUT 3.0

Every class and interface doc comment should include a @since tag, and any methods or fields added after the initial release of the class or interface should have @since tags in their doc comments.

@serial description

This tag should appear in the doc comment for any field that is part of the serialized state of a Serializable class. For classes that use the default serialization mechanism, this means all fields that are not declared transient, even fields declared private. The description should be a brief description of the field and of its purpose within a serialized object.

@serialField name type description

A Serializable class can define its serialized format by declaring an array of ObjectStreamField objects in a field named serialPersistentFields. For such a class, the doc comment for serialPersistentFields should include a @serialField tag for each element of the array. Each tag specifies the name, type, and description for a particular field in the serialized state of the class.

@serialData description

A Serializable class can define a writeObject() method to write additional data besides that written by the default serialization mechanism. An Externalizable class defines a writeExternal() method that is responsible for writing the complete state of an object to the serialization stream. The @serialData tag should be used in the doc comments for these writeObject() and writeExternal() methods, and the description should document the serialization format used by the method.

@beaninfo info

This nonstandard tag provides information about JavaBeans components and their methods. This tag is not used by javadoc, but it is apparently used by a tool internal to Sun that extracts information from @beaninfo tags for a class and outputs an appropriate java.beans.BeanInfo class. This tag appears in the source code of the Swing component classes in Java 1.2. A typical usage looks like this:

@beaninfo        bound: true
           description: the background color of this JavaBeans component

7.3.3. Doc Comments for Packages

Documentation comments for classes, interfaces, methods, constructors, and fields appear in Java source code immediately before the definitions of the features they document. javadoc can also read and display summary documentation for packages. Since a package is defined in a directory, not in a single file of source code, javadoc looks for the package documentation in a file named package.html in the directory that contains the source code for the classes of the package.

The package.html file should contain simple HTML documentation for the package. It can also contain @see, @link, @deprecated, and @since tags. Since package.html is not a file of Java source code, the documentation it contains should not be a Java comment (i.e., it should not be enclosed within /** and */ characters). Finally, any @see and @link tags that appear in package.html must use fully qualified class names.

In addition to defining a package.html file for each package, you can also provide high-level documentation for a group of packages by defining an overview.html file in the source tree for those packages. When javadoc is run over that source tree, it uses overview.html as the highest level overview it displays.