Java in a Nutshell, 5th Edition [Electronic resources] نسخه متنی

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="/image/library/english/10146_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="/image/library/english/10146_logo.gif">
This is <a href=">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

packagel in the directory that
contains the source code for the classes of the package.

The

packagel file should contain simple HTML
documentation for the package. It can also contain
@see, @link,
@deprecated, and @since tags.
Since

packagel 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

packagel must use fully qualified class
names.

In addition to defining a

packagel file for each package, you can also
provide high-level documentation for a group of packages by defining
an

overviewl file in the source tree for
those packages. When

javadoc is run over that
source tree, it uses

overviewl as the
highest level overview it displays.