19.2. Tags
Doc comments can contain tags that hold particular kinds of information. Tags come in two forms:
Block tags define stand-alone text elements. All these tags start with @, as in @see or
@deprecated. These paragraphs are treated specially in the generated documentation, resulting in
marked paragraphs, links to other documentation, and other special treatment. This section describes
all tags except @serial, @serialData, and @serialField, which relate to object serialization
and are described in "The Object Byte Streams" on page 549.•
In-line tags can occur anywhere within the text of a documentation comment and are used to apply
special formatting, such as {@code} for use of code font, or to produce special text, such as creating
a hypertext link using {@link}. In-line tags all have the form {@tag-name args} where the
optional args value might provide text to be formatted or the target of the link, for example.•
Except for tagged paragraphs and in-line tags, text in a doc comment is treated as input text for HTML. You
can create paragraph breaks in the documentation with the standard
tag, blocks of example code using
, and so on.
Not all tags need be processed by the javadoc tool by default; consult your tool documentation for details
on what is needed to process which tags.
19.2.1. @see
The @see tag creates a cross-reference link to other javadoc documentation. You can name any identifier,
although you must qualify it sufficiently. You can, for example, usually name a member of a class with its
simple name. However, if the member is an overloaded method, you must specify which overload of the
method you mean by listing the types of parameters. You can specify an interface or class that is in the current
package by its unqualified name, but you must specify types from other packages with fully qualified names.
You specify members of types by a # before the member name. The following are all potentially valid @see
tags:
@see #getName
@see Attr
@see com.magic.attr.Attr
@see com.magic.attr.Deck#DECK_SIZE
@see com.magic.attr.Attr#getName
@see com.magic.attr.Attr#Attr(String)
@see com.magic.attr.Attr#Attr(String, Object)
@see com.magic.attr
@see Attribute Specification
@see "The Java Developer's Almanac"
The first form refers to the method getName in the same class or interface as the doc comment itself, or in
any enclosing class or interface; the same syntax can be used for constructors and fields. The second form
refers to a class in the current package or an imported package. The third refers to a class by its fully qualified
name.
The next four @see forms refer to members. The first two show forms for a field (DECK_SIZE) or method
(getName). We can simply use the name of a method because exactly one getName method is defined in
the Attr class. The next two forms refer to constructors of the Attr class, one that takes a String
argument and another that takes a String and an Object. When a constructor or method is overloaded you
must specify the arguments of the one you mean.