CHAPTER 18: Documentation Comments

Previous

Java Language

Index

Next

18.4 Tagged Paragraphs

A line of a documentation comment that begins with the character @ followed by one of a few special keywords starts a tagged paragraph. The tagged paragraph also includes any following lines up to, but not including, either the first line of the next tagged paragraph or the end of the documentation comment.

Tagged paragraphs identify certain information that has a routine structure, such as the intended purpose of each parameter of a method, in a form that the documentation comment processor can easily marshal into standard typographical formats for purposes of presentation and cross-reference.

Different kinds of tagged paragraphs are available for class and interface declarations and for method, field, and constructor declarations.

18.4.1 The @see Tag

The following are examples of @see paragraphs, which may be used in any documentation comment to indicate a cross-reference to a class, interface, method, constructor, field, or URL:

@see java.lang.String
@see String
@see java.io.InputStream;
@see String#equals
@see java.lang.Object#wait(int)
@see java.io.RandomAccessFile#RandomAccessFile(File, String)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>

The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name.

A documentation comment may contain more than one @see tag.

18.4.2 The @author Tag

The following are examples of @author taglines, which may be used in documentation comments for class and interface declarations:

@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker

The information in an @author paragraph has no special internal structure.

A documentation comment may contain more than one @author tag. Alternatively, a single @author paragraph may mention several authors:

@author Jack Kent, Peggy Parish, Crockett Johnson,
	James Marshall, Marjorie Weinman Sharmat,
	Robert McCloskey, and Madeleine L'Engle

However, we recommend specifying one author per @author paragraph, which allows the documentation processing tool to provide the correct punctuation in all circumstances.

18.4.3 The @version Tag

The following is an example of a @version paragraph, which may be used in documentation comments for class and interface declarations:

@version 493.0.1beta

The information in a @version paragraph has no special internal structure.

A documentation comment may contain at most one @version tag.

18.4.4 The @param Tag

The following are examples of @param paragraphs, which may be used in documentation comments for method and constructor declarations:

@param file the file to be searched
@param pattern
	the pattern to be matched during the search
@param count      the number of lines to print for each match

The information in a @param paragraph should consist of the name of the parameter followed by a short description.

A documentation comment may contain more than one @param tag. The usual convention is that if any @param paragraphs are present in a documentation comment, then there should be one @param paragraph for each parameter of the method or constructor, and the @param paragraphs should appear in the order in which the parameters are declared.

18.4.5 The @return Tag

The following is an example of a @return paragraph, which may be used in documentation comments for declarations of methods whose result type is not void :

@return the number of widgets that pass the quality test

The information in a @return paragraph has no special internal structure. The usual convention is that it consists of a short description of the returned value.

A documentation comment may contain at most one @return tag.

18.4.6 The @exception Tag

The following is an example of an @exception paragraph, which may be used in documentation comments for method and constructor declarations:

@exception IndexOutOfBoundsException
				the matrix is too large
@exception UnflangedWidgetException the widget does not
				have a flange, or its flange has size zero
@exception java.io.FileNotFoundException the file
				does not exist

The information in an @exception paragraph should consist of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown.

A documentation comment may contain more than one @exception tag.