Section 7.3. Java Documentation Comments

7.3. Java Documentation Comments

Most ordinary comments within Java code explain the implementation details of that code. By 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 type or member definition and contains documentation for that type or member. 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 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 static 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 type or member 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 may be followed by any number of other sentences and paragraphs that describe the class, interface, method, or field in full detail.

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

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 following doc-comment tags are recognized by javadoc; 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/04

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 can be used only in doc comments for methods and constructors. 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. For readability in source-code form, consider using 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 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 tag can be used only for method and constructor comments. The @throws tag is a synonym for @exception.

@throws full-classname description: This tag is a synonym for @exception.
@see reference: Adds a "See Also:" entry that contains the specified reference. This tag can appear in any kind of doc comment. The syntax for the reference is explained in Section 7.3.4 later in this chapter.
@deprecated explanation: This tag specifies that the following type or member 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: Specifies when the type or member was added to the API. This tag should be followed by a version number or other version specification. For example:

@since JNUT 3.0

Every doc comment for a type should include an @since tag, and any members added after the initial release of the type should have @since tags in their doc comments.

@serial description

Technically, the way a class is serialized is part of its public API. If you write a class that you expect to be serialized, you should document its serialization format using @serial and the related tags listed below. @serial 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, including fields declared private. The description should be a brief description of the field and of its purpose within a serialized object.

As of Java 1.4, you can also use the @serial tag at the class and package level to specify whether a "serialized form page" should be generated for the class or package. The syntax is:

@serial include
@serial exclude

@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 an @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 data other than that written by the default serialization mechanism. An Externalizable class defines a writeExternal() method 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.

7.3.3. Inline Doc Comment Tags

In addition to the preceding tags, javadoc also supports several inline tags that may appear anywhere that HTML text appears in a doc comment. Because these tags appear directly within the flow of HTML text, they require the use of curly braces as delimiters to separate the tagged text from the HTML text. Supported inline tags include the following:

{@link reference}: In Java 1.2 and later, 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. An {@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. The reference for the {@link} tag uses the syntax described next in Section 7.3.4. For example:

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

{@linkplain reference}: In Java 1.4 and later, the {@linkplain} tag is just like the {@link} tag, except that the text of the link is formatted using the normal font rather than the code font used by the {@link} tag. This is most useful when reference contains both a feature to link to and a label that specifies alternate text to be displayed in the link. See Section 7.3.4 for a discussion of the feature and label portions of the reference argument.
{@inheritDoc}: When a method overrides a method in a superclass or implements a method in an interface, you can omit a doc comment, and javadoc automatically inherits the documentation from the overridden or implemented method. As of Java 1.4, however, the {@inheritDoc} tag allows you to inherit the text of individual tags. This tag also allows you to inherit and augment the descriptive text of the comment. To inherit individual tags, use it like this:

@param index @{inheritDoc}
@return @{inheritDoc}

To inherit the entire doc comment, including your own text before and after it, use the tag like this:

This method overrides {@link java.langObject#toString}, documented as follows:
<P>{@inheritDoc} 
<P>This overridden version of the method returns a string of the form...

{@docRoot}: This inline tag takes no parameters and is replaced with a reference to the root directory of the generated documentation. It is useful in hyperlinks that refer to an external file, such as an image or a copyright statement:

<img src="{@docroot}/images/logo.gif">
This is <a href="{@docRoot}/legal.html">Copyrighted</a> material.

{@docRoot} was introduced in Java 1.3.

{@literal text}: This inline tag displays text literally, escaping any HTML in it and ignoring any javadoc tags it may contain. It does not retain whitespace formatting but is useful when used within a <pre> tag. {@literal} is available in Java 5.0 and later.
{@code text}: This tag is like the {@literal} tag, but displays the literal text in code font. Equivalent to:

<code>{@literal text}</code>

{@code} is available in Java 5.0 and later.

{@value}: The {@value} tag, with no arguments, is used inline in doc comments for static final fields and is replaced with the constant value of that field. This tag was introduced in Java 1.4 and is used only for constant fields.
{@value reference}: This variant of the {@value} tag includes a reference to a static final field and is replaced with the constant value of that field. Although the no-argument version of the {@value} tag was introduced in Java 1.4, this version is available only in Java 5.0 and later. See Section 7.3.4 for the syntax of the reference.

7.3.4. Cross-References in Doc Comments

The @see tag and the inline tags {@link}, {@linkplain} and {@value} all encode a cross-reference to some other source of documentation, typically to the documentation comment for some other type or member.

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, it is expected to have the following form:

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, type, or type member, using one of the following forms:

pkgname: A reference to the named package. For example:

@see java.lang.reflect

pkgname.typename: A reference to a class, interface, enumerated type, or annotation type specified with its full package name. For example:

@see java.util.List

typename: A reference to a type 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.

typename# methodname: A reference to a named method or constructor within the specified type. For example:

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

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

typename# methodname( paramtypes): A reference to a method or constructor with the type of its parameters explicitly specified. This is useful when cross-referencing an overloaded method. For example:

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

# methodname: A reference to a nonoverloaded 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)

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

@see java.io.BufferedInputStream#buf

If the type is specified without its package name, it is resolved as described for typename.

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

@see #x

7.3.5. 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 be HTML and 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.