Java Reference
In-Depth Information
@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
later in this chapter in
“Cross-References in Doc Comments” on page 233
.
@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, sug‐
gest 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
}.
The
@deprecated
tag is an exception to the general rule that
javac
ignores all
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 for‐
mat using
@serial
and the related tags listed next.
@serial
should appear in
