Java Reference
In-Depth Information
the doc comment for any field that is part of the serialized state of a
Serializa
ble
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.
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.
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:
s
{@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. 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
“Cross-References in Doc Comments” on page
233
. For example:
