This specification is not final and is subject to change. Use is subject to license terms.
Java SE 24 & JDK 24 DRAFT 24-loom+10-110
JavaDoc Documentation Comment Specification for the
Standard Doclet (JDK 24)
This document specifies the form of documentation comments recognized
by the standard
doclet for the javadoc tool in JDK 24, used
to generate HTML documentation for an API.
In the context of the javadoc tool, the interpretation
of the content of a documentation comment is up to doclet that is used
to process the comment. Other doclets may accept the same syntax as the
standard doclet, or they may support an alternate syntax. However, due
to support in many tools, the syntax supported by the standard doclet
has become a de facto standard.
Documentation Comments
Documentation comments are stylized comments appearing in source
code, near to the declarations that they serve to document.
Documentation comments are recognized only when placed immediately
before the declaration of a module, package, class, interface,
constructor, method, annotation interface element, enum member, or
field. In other words, a documentation comment should appear before any
annotation, modifier, keyword, identifier, or other Java construct that
is part of the declaration.
Either kind, or both kinds, may be used in any one source file.
Only one documentation comment per declaration statement is
recognized. If there are multiple documentation comments before a
declaration, the one closest to the beginning of the declaration is
used.
Documentation may also be provided in certain files:
package.html: For historical compatibility, the
documentation for a package may be provided in a file called
package.html in the source directory for the package. In
general, it is now recommended to provide a documentation comment in a
file named package-info.java, which may also contain import
statements and annotations for the package declaration.
doc-files/*.{html,md}: Additional documentation for a package
may be provided in HTML files and Markdown files in a
doc-files subdirectory of the source directory for the
package.
HTML files are identified by a filename ending in .html.
The content of the <main> element of an HTML file, or
the <body> element if there is no
<main> element is processed as if it were the content
of a traditional documentation comment.
Markdown files are identified by a filename ending in
.md. The content of a Markdown file is processed as if it
were the content of a Markdown documentation comment.
Traditional Documentation
Comments
Traditional documentation comments are traditional
comments that begin with /**. If any line in such a
comment begins with asterisks after
any leading whitespace, the leading whitespace and asterisks are
removed. Any whitespace appearing after the asterisks is not
removed.
A traditional documentation comment may contain HTML content, inline
tags, and block tags. You can also use escape sequences to represent characters
that would otherwise be inconvenient or difficult to represent.
Markdown Documentation
Comments
Documentation comments containing Markdown are composed of a series
of consecutive lines, each beginning with optional whitespace followed
by ///.
The overall form of a documentation comment is an initial main description, followed by a series of
block tags, which provide additional
information about the declaration to which the comment applies.
Descriptive text may include inline tags, HTML content, and Markdown content, as described below.
It is possible to have a comment with only block tags and no main
description.
For historical reasons, the documentation comment for a package may
instead be provided in a file called package.html in a source
directory for the package. In this case, the documentation comment is
the content of the <body> tag, and all references to
Java types (for example, in see tags) must be fully
qualified. The standard doclet also allows additional documentation to
be provided in files such as overview.html. The rules for such
content are the same as for package.html.
Main Description
The main description in a documentation comment is the content from
the beginning of the comment, up to the first block tag, if there are
any, or to the end of the comment, if there are none. Leading and
trailing whitespace is ignored. If there is no such content, the main
description is said to be missing.
The main description cannot continue after any block tags.
Examples of a missing main description.
No content before the first block tag:
/**
* @param ...
* ...
*/
An empty documentation comment:
/**
*
*/
The first sentence of the main description should be a summary
sentence that contains a concise but complete description of the
declared entity.
Block Tags
Block tags are of the form @identifiercontent and give additional details to be incorporated into the
generated documentation. Each block tag must appear at the beginning of
a line, ignoring leading asterisks, whitespace characters, and the
initial comment delimiter (/**). This means you can use the
@ character elsewhere in the text, and it will not be
interpreted as the start of a tag. If you want to start a line with the
@ character and not have it be interpreted, then use the
HTML entity @. The content of a block tag is any
text following the tag up to, but not including, either the next block
tag, or the end of the documentation comment. The content can span
multiple lines.
There can be any number of block tags; some types of tags can be
repeated while others cannot.
Inline Tags
Inline tags are of the form {@identifiercontent} and provide details within the context of
the enclosing description. They may generally appear wherever
descriptive text and HTML is permitted, although some inline tags may
only be used at the beginning of the main description.
Some inline tags may contain free-form text. When such text
explicitly contains braces, the braces must be "balanced", implying an
equal number of appropriately nested left brace and right brace
characters, so that the closing brace of the inline tag can be
determined. No other lexical analysis of the text is performed; in
particular, there is no special consideration of characters like
', ", \, and @.
Lines beginning with @ that are enclosed within an
inline tag are not considered as beginning a block tag.
When the text content is HTML, it may be possible to use entities
{ and } to represent
unbalanced braces.
HTML Content
HTML content is not formally checked, although some tools may provide
some amount of checking to help catch common errors.
In order to be able to generate documentation that conforms to the
appropriate standards, the following considerations should be taken into
account when using HTML constructs in a documentation comment:
To support properly structured headings within the pages of
generated documentation, headings in the documentation comments for
module, package, and type declarations (including nested types) should
start at heading
level 2 and increase accordingly as needed; likewise, headings in
the documentation comments for constructors, methods, fields and other
members should start at heading level 4. In standalone HTML files, such
as in a doc-files subdirectory,
headings should start at heading level 1.
To avoid the possibility of a conflict with the unique
identifiers used to identify positions within the generated
documentation for the declaration of program elements, the values of
user-defined id attributes should contain a character (such
as -) that is not a valid character in a Java
identifier.
Markdown Content
Because horizontal whitespace at the beginning and end of each line
of Markdown code may be significant, the content of such a comment is
determined as follows:
Any leading whitespace and the three initial /
characters are removed from each line.
The lines are shifted left, by removing leading whitespace
characters, until the non-blank line with the least leading whitespace
has no remaining leading whitespace.
Additional leading whitespace and any trailing whitespace in each
line is retained, because it may be significant. For example, whitespace
at the beginning of a line may indicate an indented
code block, and whitespace at the end of a line may indicate a hard line
break.
Note: The policy to remove leading incidental whitespace is
similar to that for String.stripIndent,
except that there is no need for any special treatment for a trailing
blank line.
There are no restrictions on the characters that may appear after the
/// on each line of the comment. In particular, the comment
may contain code samples which may contain comments of their own:
/// Here is an example:
///
/// ```
/// /** Hello World! */
/// public class HelloWorld {
/// public static void main(String... args) {
/// System.out.println("Hello World!"); // the traditional example
/// }
/// }
/// ```
As well as serving to visually distinguish the new kind of
documentation comment, the use of end-of-line (//) comments
eliminates the restrictions on the content of the comment that are
inherent with the use of traditional (/* ... */) comments.
In particular, it is not possible to use the character sequence
*/ within a traditional comment, (JLS
3.7) although it may be desirable to do so when writing example code
containing traditional comments, strings containing "glob" expressions,
and strings containing regular expressions.
Note: For a blank line to be included in the comment, it
must begin with any optional whitespace followed by ///. A
completely blank line will cause any preceding and following comment to
be treated as separate comments, in which case, all but the last comment
will be discarded, and only the last comment will be considered as a
documentation comment for any declaration that may follow.
For example:
/// This is an example ...
///
/// ... of a 3-line comment containing a blank line.
The blank line in the following example will terminate the first
comment, so that the comment that comes after the blank line will be
treated as a separate comment.
/// This comment will be treated as a "dangling comment" and will be ignored.
/// This is the comment for the following declaration.
public void m() { }
The same is true for any other comment not beginning with
/// that may appear between two ///
comments.
Syntax
The overall syntax of a Markdown documentation comment is that of the
CommonMark variant of
Markdown. Enhancements to links allow convenient linking to other
program elements. Simple GFM pipe
tables are supported, as are all JavaDoc tags.
Headings
Both ATX
headings and setext
headings are supported. Unlike HTML headings, Markdown headings
should start at level 1 and increase from there, whatever the context of
the documentation comment. (They will be translated to the correct
heading level in the generated documentation.)
Links
The general form of a reference
link is [text][label] where text is the
text to be displayed, and label is a label for the
destination of the link, and which is subsequently defined by a line of
the form [label]:uri. Collapsed
and shortcut
forms can also be used when the label is the same as the
text.
In a documentation comment, if the label for a reference link is to
be defined explicitly, it must be defined in the same documentation
comment. But, if it is not defined and if it syntactically matches that
of a reference to a program element, then it
is implicitly defined as a reference to that program element. It is an
error if the label looks like a reference to a program element but there
is no such element.
The following all represent links to
java.lang.Object#hashCode(), albeit with different text to
be displayed:
[the default hashcode for an object][java.lang.Object#hashCode()]
[the default hashcode][Object#hashCode()] — no need for
the fully qualified name in this case
[Object#hashCode()][] — using the collapsed form of a
reference link
[Object#hashCode()] — using the shortcut form of a
reference link
You can link to any kind of program element, as shown in the
following examples:
/// * a module [java.base/]
/// * a package [java.util]
/// * a class [String]
/// * a field [String#CASE_INSENSITIVE_ORDER]
/// * a method [String#chars()]
Inline
links are also supported in documentation comments, but the helpful
recognition of program elements as labels means that reference links are
generally more useful than inline links.
According to the standard rules for reference links, you must escape
any use of square brackets within a reference. This might occur when you
are creating a reference to a method with an array parameter. The
following shows a link to String.copyValueOf(char[])
[String#copyValueOf(char\[\])]
The normal rendering for a reference link is to use the default plain
font. If you wish to use a monospace font, you must enclose the text
within a code span, using backticks. For references to program elements,
monospace font will be used automatically if the text is the same as the
reference (such as when using the collapsed or shortcut forms), and the
default plain font otherwise. The following shows how these forms
correspond to the existing link and linkplain tags.
[an object][Object] ⇒
{@linkplain Object an object}
[Object][] ⇒ {@link Object}
[Object] ⇒ {@link Object}
[`a link in monospace font`][Object] ⇒
{@link Object a link in monospace font}
[a link with `mixed` fonts][Object] ⇒
{@linkplain Object a link with {@code mixed} fonts}
Note: You cannot use a reference link in the first sentence
of any documentation comment that refers to a user-defined link
reference definition elsewhere in the documentation comment; you can use
an inline link in this situation instead.
Tables
Simple tables are supported, using the syntax defined in GitHub Flavored Markdown. For
example, a simple table might be written as follows:
/// | Latin | Greek |
/// |-------|-------|
/// | a | alpha |
/// | b | beta |
/// | c | gamma |
Note: Captions and other features that may be required for
accessibility are not supported. In such situations, the use of HTML
tables is still recommended.
Inline Tags and Block Tags
Both inline tags and block tags may be used in Markdown documentation
comments, although neither may be used within the literal text of code spans and
fenced
or indented
code blocks.
For those tags that may contain text with markup, in a Markdown
documentation comment that markup will also be in Markdown format.
As in traditional documentation comments, the content of inline tags
may span multiple lines, including blank lines.
When using a reference
link with an explicit link label,
the reference and the label must appear in the same part of the comment:
in either the main description, or in any inline or block tag. A
reference link may not refer to a label defined in a different part of
the comment, or in a different comment altogether.
The inheritDoc tag is used to
include documentation from one or more supertypes. There is no
requirement that the format of the comment containing the tag is the
same as the format of the comment containing the documentation to be
inherited. While it may be the case that comments within a library may
all use the same format, that may be less likely when handling comments
in different libraries, written by different authors.
Syntax Highlighting
and Embedded Languages
The opening fence in a fenced code
block may be followed by an info
string, the first word of which is used to derive the CSS class
name in the corresponding generated HTML, and which may be used by
JavaScript libraries to enable syntax highlighting (such as with Prism) or rendering diagrams (such as
with Mermaid).
Note: You can add JavaScript libraries to your documentation
by using the javadoc--add-script
option.
Escape Sequences
The following escape sequences are supported in traditional
documentation comments wherever text, entities and HTML may appear, to
represent characters that would otherwise be inconvenient or difficult
to represent:
@@, to represent @, to prevent it from
being interpreted as part of the introduction of a block or inline
tag,
@/, to represent /, as part of
*@/ to represent */, to avoid prematurely
terminating the enclosing comment,
@*, to represent *, where it would
otherwise be discarded at the beginning
of a line.
Escape sequences are context-sensitive, and can only be used where
the use of the escaped character by itself would have a different
syntactic interpretation. In other situations, these character sequences
are taken literally, without additional interpretation.
Escape sequences cannot be used in inline tags that contain literal
text; this includes code, literal, snippet, and user-defined tags.
References
References are the constructs in a documentation comment that refer
to elements in the surrounding declarations. Depending on the context,
they may refer to modules, packages, classes and interfaces,
constructors, methods, annotation members, fields, enum members,
parameters, record components and the names of exceptions that may be
thrown by a method or constructor.
Leading components can be omitted when they can be inferred from the
surrounding context. Trailing components can be omitted when they are
not required. Generally, the reference is evaluated in the scope in
which the documentation comment exists. In particular,
import statements for the compilation unit are taken into
account when evaluating class and interface names.
The class may be any top-level or nested class or
interface.
The member may be any constructor, method, annotation
member, field or enum member, but not a nested class or interface. As in
Java source code, a constructor is identified by using the name of its
class. The name of a constructor or method should normally be followed
by the list of its parameter types, enclosed in parentheses, although
the parameter types and parentheses can be omitted if the method or
constructor is not overloaded and the name is not also that of a field
or enum member in the same class or interface. When a parameter list is
given, whitespace characters may appear between tokens in the parameter
list; whitespace characters may not appear elsewhere in the reference.
When the reference is to a member of the same class as that containing
the documentation comment, all parts of the reference up to and
including the # may be omitted, although the '#' may be
retained for clarity.
Parameterized types may be used in the class and member parts of the
reference; annotations may not be used anywhere in the reference.
Whitespace characters may occur between tokens within the parameter list
for a constructor or method. A trailing / can be added to a
name to refer to a module in the presence of a package or class with the
same name.
Note: You cannot refer to the declaration of a specific
parameter or record component with this form.
An alternative form is provided to generate references to arbitrary
URI fragments in the generated documentation such as headings in
documentation comments. This form uses a double hash mark
(##) as separator:
module/package.class##fragment
fragment is interpreted as URI fragment within the page
documenting the specified program element.
Other tags, such as param, throws, and serialField may only provide
support for the specific kinds of references that are relevant to each
tag. See the description of individual tags for more details.
Method Documentation
A documentation comment for a method declaration must at least
provide the following:
a return tag for the result,
if the return type is not void,
a param tag per formal parameter, if any,
a throws tag per exception
type, checked or unchecked, in the throws clause, if
any.
It is an error if any item described in that list is missing from a
documentation comment of a method declaration and either of following is
true:
the declaration is not overriding, or
the declaration is overriding and if the item were provided with an
inheritDoc tag in its content, it
would be an error.
Otherwise, a missing item is considered as if it were provided with
{@inheritDoc} as its content.
For the purpose of this specification an overriding method
declaration is a method declaration that could be annotated with
@Override (JLS
9.6.4.4), but is not an accessor method declaration for a record
component.
Method documentation allows inheritance by omission: if a
documentation comment for a method declaration provides only some of the
items, the rest are assumed to be inherited. For example, if this is
provided:
/**
* @param scale a non-zero number
* @throws IllegalArgumentException if scale is 0
*/
@Override
<T> T magnify(int scale, T element) throws MagnificationException
This is assumed:
/**
* {@inheritDoc}
*
* @param <T> {@inheritDoc}
* @param scale a non-zero number
* @param element {@inheritDoc}
* @return {@inheritDoc}
* @throws IllegalArgumentException if scale is 0
* @throws MagnificationException {@inheritDoc}
*/
@Override
<T> T magnify(int scale, T element) throws MagnificationException
However, not all missing items can be inherited. For example, if a
method declares an exception X that is not documented by
any of the methods that this method overrides, then documentation item
for that exception cannot be inherited and can only be provided by this
method's documentation comment. (Adding or assuming
@throws X {@inheritDoc} would be an error.) If that item is
not provided, it is considered missing.
(@Override is only added to these examples to emphasize
that the declarations are overriding; that annotation has no effect on
documentation.)
Note: A documentation comment consisting of a sole
inheritDoc tag explicitly provides only the main
description of a method:
/**
* {@inheritDoc}
*/
Other items, if any, are inherited by omission.
Note: It is the overriding method, not the overridden
method, that determines which items are missing and which are not.
For example, if an overriding method declares a thrown exception
X, but that method's documentation comment does not contain
@throws X ..., then that documentation item is missing. If
an overriding method does NOT declare a thrown exception, even if the
overridden method does, then that documentation item is NOT missing.
This behavior is usually noticed when dealing with unchecked
exceptions. Since unchecked exceptions do not normally appear in the
throws clause, unless explicitly documented, they will not
be missing. This gives rise to a misconception that the standard doclet
treats checked exceptions differently from unchecked exceptions, which
it does not.
In fact, a similar behavior might be replicated with checked
exceptions. Consider a method that declares two checked exceptions
X and Y, such that X is a
supertype of Y. If an overriding method declares
X but not Y, then @throws Y ...
won't be missing.
Overriding Methods
in Classes and Interfaces
When a method declaration overrides a method in the superclass or an
extended superinterface, the standard doclet generates the subheading
"Overrides" in the documentation for the overriding method.
When a method declaration in a class overrides a method in an
interface, the standard doclet generates the subheading "Specified by"
in the documentation for the overriding method.
In both cases, a link to the overridden method is included.
Standard Tags
The following sections describe the standard block and inline tags
supported by the standard doclet.
Note: The standard doclet also supports user-defined tags
conforming to the same general syntactic rules.
author
@authorname-text
Adds an "Author" entry with the specified name text to the generated
documents when the -author option is used. A documentation
comment can contain multiple author tags. You can specify
one name per author tag or multiple names per tag. In the
former case, the standard doclet inserts a comma (,) and a
space between names. In the latter case, the entire text is copied to
the generated document without being parsed. Therefore, you can use
multiple names per line if you want a localized name separator other
than a comma.
If there are no author tags in the description for a
member class or interface, the standard doclet will (recursively) look
for any such tags in the enclosing class or interface.
Introduced in JDK 1.0.
code
{@codetext}
Equivalent to <code>{@literaltext}</code>.
Displays text in code font without interpreting the text as
HTML markup or nested Javadoc tags. This enables you to use regular
angle brackets (< and >) instead of the
HTML entities (< and >) in
documentation comments, such as in parameter types
(<Object>), inequalities (3 < 4), or
arrows (->). For example, the documentation comment text
{@code A<B>C} displayed in the generated HTML page
unchanged as A<B>C. This means that the
<B> is not interpreted as bold and is in code font.
If you want the same functionality without the code font, then use the
literal tag.
Introduced in JDK 1.5.
deprecated
@deprecateddeprecated-text
This tag is used in conjunction with the @Deprecated
annotation to indicate that this API should no longer be used (even
though it may continue to work). The standard doclet moves deprecated
text ahead of the main description, placing it in italics and preceding
it with a bold warning.
The first sentence of deprecated text should tell the user when the
API was deprecated and what to use as a replacement. The standard doclet
copies the first sentence to the summary section and index. Subsequent
sentences can also explain why it was deprecated. You should include a
link tag that points to the replacement API.
Note:
For historical reasons, when used in a traditional documentation
comment, the use of the deprecated tag is enough by
itself to mark the associated declaration as deprecated, even if the
@Deprecated annotation is not used.
In Markdown documentation
comments, the @Deprecated annotation must be used to
mark the declaration as deprecated; the deprecated tag is
just an adjunct to provide descriptive details.
The tag will be ignored if the annotation is not also present.
Introduced in JDK 1.0.
docRoot
{@docRoot}
Represents the relative path to the generated document's
(destination) root directory from any generated page. This tag is useful
when you want to include a file, such as a copyright page or company
logo, that you want to reference from all generated pages. Linking to
the copyright page from the bottom of each page is common.
The docRoot tag can be used both on the command line and
in a documentation comment. The tag is valid in all documentation
comments: overview, module, package, class, interface, constructor,
method and field, including the text portion of any tag (such as the
return, param and deprecated
tags).
For example, on the command line, where the header, footer, or bottom
are defined:
When you use the docRoot tag this way in a make file,
some makefile programs require a special way to escape for the brace
{} characters. For example, the Inprise MAKE version 5.2
running on Windows requires double braces: {{@docRoot}}. It
also requires double (rather than single) quotation marks to enclose
arguments to options such as the -bottom option (with the
quotation marks around the href argument omitted).
For example, in a documentation comment:
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
This tag is needed because the generated documents are in
hierarchical directories, as deep as the number of subpackages. The
expression <a href="{@docRoot}/copyright.html">
resolves to <a href="../../copyright.html"> for
java/lang/Object.java and
<a href="../../../copyright.html"> for
java/lang/ref/Reference.java.
Introduced in JDK 1.3.
exception
@exceptionexception-namedescription
This tag is equivalent to the throws tag, which is now the recommended
form.
Introduced in JDK 1.0.
hidden
@hidden
Hides a program element from the generated API documentation. This
tag may be used when it is not otherwise possible to design the API in a
way that such items do not appear at all.
Introduced in JDK 9.
index
{@indexworddescription}
{@index "phrase"description}
Declares that a word or phrase, together with an optional short
description, should appear in the index files generated by the standard
doclet. The index entry will be linked to the word or phrase that will
appear at this point in the generated documentation. The description may
be used when the word or phrase to be indexed is not clear by itself,
such as for an acronym.
Introduced in JDK 9.
inheritDoc
{@inheritDoc}
{@inheritDocsupertype}
Indicates that a method documentation comment part that contains this
tag is the same as that of the overridden method in a superclass or
superinterface, which is either determined automatically or
specified.
It is an error if the overridden method is missing the corresponding
part.
This tag enables you to write more general comments higher up the
inheritance hierarchy and to write around the inherited parts.
This tag is valid only in these places in a documentation comment of
an overriding declaration of a method:
If the corresponding part of the overridden method's documentation
comment itself uses an inheritDoc tag, then that tag is
processed first. (This might be applied recursively as required.)
Let m be a method declaration in a class or interface
T. If the documentation comment for m contains
an inheritDoc tag then the superclass or superinterface
(whose overridden method this tag will use the corresponding part of) is
determined as follows:
If the tag has the form {@inheritDoc S}, then the
superclass or superinterface is S. It is an error,
if m does not override from T a method in
S.
If the tag has the form {@inheritDoc}, then the
superclass or superinterface is determined using automatic supertype
search. It is an error if the automatic search cannot determine
it.
Automatic Supertype Search
The search for the supertype is performed in two phases: the
recursive phase, then the final phase. For simplicity, the search starts
from S, where S = T, although there's nothing
to be found in T (otherwise, the search would not be
required). When starting from S, where S = T,
the first condition always breaks into "otherwise" because a method does
not override itself (JLS
8.4.8.1).
Recursive phase
If S declares a method that T.m overrides,
then S is a supertype, otherwise:
If S is a class that has a direct superclass (JLS
8.1.4) that is not java.lang.Object, then the recursive
phase of the search is applied to that superclass. If that application
has not found a supertype, then:
If S has direct superinterfaces (JLS
8.1.5), then the recursive phase of the search is applied to each of
those superinterfaces, in the order that they are listed in the
extends (if S is a class) or
implements (if S is an interface) clause,
until the supertype found or superinterfaces are exhausted.
Final phase
If the recursive phase of search has not found the supertype, then
one final attempt is made to see if java.lang.Object is the
supertype. If T is a class and m overrides a
method in java.lang.Object, or T is an
interface and m's signature is override-equivalent to the
signature of a public method in java.lang.Object (JLS
8.4.2), then java.lang.Object is the supertype.
Otherwise, the search has not found the supertype.
Note: The search is performed in two phases so as to not
prematurely consider java.lang.Object as the supertype.
Sometimes java.lang.Object provides overly general
documentation for its public methods (such as equals,
hashCode, toString) when more specific
documentation is available.
For example, consider this schematic hierarchy:
interface A
interface B extends A
interface C
class D implements B, C
interface E
class F extends D implements E
The automatic supertype search traverses that hierarchy in the following
order: F, D, B, A,
C, E, java.lang.Object.
Note: The source file for an inherited method must be on the
source path for the documentation comment to be available for copy.
Neither the class nor its package needs to be passed in on the command
line.
Note: When using Markdown comments, there is
no requirement that the comment containing the tag and the comment
containing the documentation inherited by that tag should either be both
Markdown documentation comments or both traditional (not Markdown)
comments.
Introduced in JDK 1.4; accepts an optional argument since JDK 22.
link
{@linkreferencelabel}
Inserts an inline link with a visible text label that points to the
documentation for the specified module, package, class, or member name
of a referenced class. This tag is valid in all documentation comments:
overview, module, package, class, interface, constructor, method and
field, including the description part of any tag, such as the
return, param and deprecated
tags.
This tag is similar to the third form of the see tag. The main difference is that the
link tag generates an inline link rather than placing the
link in the "See Also" section. The link tag begins and
ends with braces to separate it from the rest of the inline text. If you
need to use the right brace (}) inside the label, then use
the HTML entity notation }.
There is no limit to the number of link tags allowed in
a sentence.
For example, here is a comment that refers to the
getComponentAt(int, int) method:
Use the {@link #getComponentAt(int, int) getComponentAt} method.
From this code, the standard doclet generates the following HTML
(assuming it refers to another class in the same package):
Use the <a href="Component.html#getComponentAt(int,int)">getComponentAt</a> method.
The previous line appears on the web page as:
Use the getComponentAt method.
Introduced in JDK 1.2.
linkplain
{@linkplainreferencelabel}
Behaves the same as the link tag, except the link label
is displayed in plain text rather than code font. Useful when the label
is plain text. For example,
Refer to {@linkplain #add() the overridden method}.
is displayed as:
Refer to the overridden method.
Introduced in JDK 1.4.
literal
{@literaltext}
Displays text without interpreting the text as HTML markup or nested
Javadoc tags. This enables you to use angle brackets (<
and >) instead of the HTML entities
(< and >) in documentation
comments, such as in parameter types (<Object>),
inequalities (3 < 4), or arrows (->).
For example, the documentation comment text
{@literal A<B>C} displays unchanged in the generated
HTML page in your browser, as A<B>C. The
<B> is not interpreted as bold (and it is not in code
font). If you want the same functionality with the text in code font,
then use the code tag.
Introduced in JDK 1.5.
param
@paramparameter-namedescription
@param<type-parameter-name>description
Adds a parameter with the specified parameter name followed by the
specified description to the "Parameters" section. The description may
continue onto multiple lines. This tag is valid only in a documentation
comment for a method, constructor, or class. The parameter name can be
the name of a parameter in a method or constructor, or the name of a
type parameter of a class, method, or constructor. Use angle brackets
(< >) around such a parameter name to indicate the
use of a type parameter.
Example of a type parameter of a class:
/**
* @param <E> Type of element stored in a list
*/
public interface List<E> extends Collection<E> { ... }
Example of parameters, including type parameters, of a method:
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) { ... }
When an inheritDoc tag is used
in the description of a method formal or type parameter, the
corresponding part of the overridden method documentation is matched
using the parameter's position, not the parameter's name (JLS
8.4.2 and JLS
8.4.4).
For example, consider the following method declaration:
/**
...
* @param scale a non-zero number
...
* @param <T> the type of the element being magnified
...
*/
<T> T magnify(int scale, T element) throws MagnificationException
Then as far as the documentation inheritance is concerned, these two
comments are equivalent:
/**
...
* @param s {@inheritDoc}
* @param e {@inheritDoc}
...
* @param <E> {@inheritDoc}
*/
@Override
<E> E magnify(int s, E e) throws MagnificationException
/**
...
* @param scale {@inheritDoc}
* @param element {@inheritDoc}
...
* @param <T> {@inheritDoc}
*/
@Override
<T> T magnify(int scale, T element) throws MagnificationException
If parameter names differ, care should be taken when inheriting such
parameter documentation because that parameter name might be referred to
from elsewhere both in the overridden and overriding methods.
Introduced in JDK 1.0.
provides
@providesservice-typedescription
This tag may only appear in the documentation comment for a module
declaration, and serves to document an implementation of a service
provided by the module. The description may be used to specify how to
obtain an instance of this service provider, and any important
characteristics of the provider.
Introduced in JDK 9.
return
@returndescription
{@returndescription}
As a block tag, adds a "Returns" section with the given description,
providing details about the values that may be returned by the
method.
As an inline tag, provides content for the first sentence of a
method's main description, and a "Returns" section, as if
"@returndescription" were also present. In the
default English locale, the first sentence is "Returnsdescription.".
This tag is valid only in a documentation comment for a method. As an
inline tag, it may only occur at the beginning of a method's main
description.
When inheriting documentation, either form of a return
tag can be used:
/**
* {@return {@inheritDoc}}
...
*/
<T> T magnify(int scale, T element) throws MagnificationException
/**
...
* @return {@inheritDoc}
*/
<T> T magnify(int scale, T element) throws MagnificationException
Introduced as a block tag in JDK 1.0, and as an inline tag in JDK
16.
see
Adds a "See Also" heading with a link or text entry that points to a
reference. A documentation comment can contain any number of
see tags, which are all grouped under the same heading. The
see tag has three variations. The form to reference other
program elements is the most common. This tag is valid in all
documentation comments. For inserting an inline link within a sentence
to a package, class, or member, use a link tag.
@see"string"
Adds a text entry for string. No link is generated. The
string may be a reference to information which is not available by URL.
The standard doclet distinguishes this from the other cases by searching
for a double quotation mark (") as the first
character.
@see<a href="url">label</a>
Adds a link as defined by the url. The URL may be a relative
or absolute URL. The standard doclet distinguishes this from other cases
by searching for a less-than symbol (<) as the first
character.
@seereferencelabel
Adds a link with a visible text label that points to the
documentation for the specified program element that is referenced.
reference can refer to any valid
program element. If this element is in the documented classes, then the
standard doclet creates a link to it.
To create links to external referenced classes, use the
-link option. External referenced classes are classes that
are not passed into the javadoc tool on the command line.
Links in the generated documentation to external referenced classes are
called external references or external links. For example, if you run
the standard doclet on only the java.awt package, then any
class in java.lang, such as Object, is an
external referenced class. Use the -link and
-linkoffline options to link to external referenced
classes. The source comments of external referenced classes are not
available to the javadoc command run.
Use either of the other two see tag forms to refer to
the documentation of a name that does not belong to a referenced
class.
label is text to be used as the link label and is optional
for references to program elements. If no label is provided for an
element reference, a default is generated, based on the target of the
reference. Use the label when you want the text to be different from the
auto-generated text. For references to URI fragments a label must be
provided. The label can contain whitespace characters.
If the content of the label appears to be a phrase, and not just a
possibly-abbreviated form of a reference to the target link, the link
will be displayed in plain font; otherwise, the link will be displayed
in monospace font.
An optional field description should explain the meaning of the field
and list the acceptable values. When needed, the description can span
multiple lines. The standard doclet adds this information to the
serialized form page.
If a serializable field was added to a class after the class was made
serializable, then a statement should be added to its main description
to identify at which version it was added.
The include and exclude arguments identify
whether a class or package should be included or excluded from the
serialized form page. They work as follows:
A public or protected class that implements
Serializable is included unless that class (or its package)
is marked with the @serial exclude tag.
A private or package-private class that implements
Serializable is excluded unless that class (or its package)
is marked with the @serial include tag.
For example, the javax.swing package is marked with the
@serial exclude tag in package-info.java. The
public class java.security.BasicPermission is marked with
the @serial exclude tag. The package-private class
java.util.PropertyPermissionCollection is marked with the
@serial include tag.
A serial tag at the class level overrides any
serial tag at the package level.
Introduced in JDK 1.2.
serialData
@serialDatadata-description
Uses the data description value to document the types and order of
data in the serialized form. This data includes the optional data
written by the writeObject method and all data (including
base classes) written by the Externalizable.writeExternal
method.
The serialData tag can be used in the documentation
comment for the readObject, writeObject,
readExternal, writeExternal,
readResolve, and writeReplace methods.
Introduced in JDK 1.2.
serialField
@serialFieldfield-namefield-typefield-description
Documents an ObjectStreamField component of the
serialPersistentFields member of a
Serializable class. Use one serialField tag
for each ObjectStreamField component.
Introduced in JDK 1.2.
since
@sincesince-text
Adds a "Since" heading with the specified since-text value
to the generated documentation. The tag indicates that the associated
program element has existed since it was introduced in the software
release specified by the since-text value. For example,
@since 11.
The text has no special internal structure, meaning that commas,
whitespace characters and other punctuation have no special
significance. Multiple since tags are allowed; for example,
you could use multiple tags when the program element is part of more
than one API. However, when used in conjunction with the feature in the
standard doclet to generate a summary page of what API is new in each
release, the since-text value of the first tag should be a
simple string with no formatting markup.
It is recommended that each top-level program element (module,
package, class or interface) should contain an appropriate
since tag. In addition, each member element (constructor,
method, field, nested class or interface) should have a tag in those
cases where the value is different from that of the enclosing class or
interface. If there are no since tags in the description
for a member class or interface, the standard doclet will (recursively)
look for any such tags in the enclosing class or interface.
Note: One or more methods may be added implicitly to a class
or interface as a result of adding additional supertypes in an
extends or implements clause, after the class
or interface was first created.
Note: Changing the return type of a method to a covariant
return type is tantamount to adding a new method with that signature,
and should be given an updated since tag. This is because
the method with that new return type could not be called in any prior
release to leverage that new return type.
Introduced in JDK 1.1.
snippet
{@snippetattributes}
{@snippetattributes : body}
Includes a fragment, or "snippet", of example code in the generated
documentation. The code may be provided inline within the tag by
specifying a bodyand/or in an
external file, specified in the attributes. Within the content,
markup tags can be placed in line comments to
identify regions within the text and instruct how to present the text in
these regions.
Additional details about the snippet can be given as
attributes, in the form of
name=value pairs, placed after the
initial tag name. An attribute name is always a simple identifier. An
attribute value may be an identifier, unsigned integer, or enclosed in
either single or double quote characters; no escape characters are
supported. An attribute value and the preceding = may be
omitted when the presence of the attribute name is sufficient.
Attributes are separated from the tag name and from each other by
whitespace characters, such as space and newline.
A snippet may specify an id attribute, which can be used
to identify the snippet in both the API and the generated HTML, and
which may be used to create a link to the snippet. In the generated
HTML, the id will be placed on the outermost element that is generated
to represent the snippet.
Code fragments are typically Java source code, but they may also be
fragments of properties files, source code in other languages, or plain
text. A snippet may specify a lang attribute, which
identifies the kind of content in the snippet. For an inline snippet,
the default value is java. For an external or a hybrid
snippet, the default value is derived from the extension of the name of
the file containing the snippet's content.
Inline snippets
An inline snippet contains the content of the snippet within the tag
itself.
The content of the snippet, which is included in the generated
documentation, is the text between the first newline after the colon
(:) and the closing curly brace (}).
There is no need to escape characters such as <,
>, and & with HTML entities, nor is
there any need to escape documentation comment tags.
Surrounding whitespace is stripped from the content using String::stripIndent.
There are two limitations on the content of inline snippets:
The character sequence */ cannot be used anywhere
within the content, because the */ would terminate the
enclosing documentation comment. This includes use of
/* ... */ comments, or within a // comment, or
within string literals, such as those used to represent regular
expressions. This restriction applies to all content in documentation
comments; it is not specific to the snippet tag.
The content of an inline snippet can only contain balanced pairs
of curly-brace characters. The overall inline tag is terminated by the
first right brace that matches the opening brace. This restriction
applies to all inline tags; it is not specific to the
snippet tag.
External snippets
An external snippet refers to a separate class or file that contains
the content of the snippet.
In an external snippet the colon, newline, and subsequent content can
be omitted.
Unlike inline snippets, external snippets have no limitations on
their content. In particular, they may contain /* ... */
comments.
The location of the external code can be specified either by class
name, using the class attribute, or by a short relative
file path, using the file attribute. In either case the
file can be placed in a package hierarchy rooted in a
snippet-files subdirectory of the directory containing the
source code with the snippet tag. Alternatively, the file
can be placed on an auxiliary search path, specified by the
--snippet-path option to the javadoc tool. The
use of snippet-files subdirectories is similar to the use
of doc-files subdirectories for auxiliary documentation
files.
The file for an external snippet may contain multiple regions, to be
referenced in different snippet tags, appearing in different parts of
the documentation.
Hybrid snippets
A hybrid snippet is both an internal snippet and an external snippet.
It contains the content of the snippet within the tag itself, for the
convenience of anyone reading the source code for the class being
documented, and it also refers to a separate file that contains the
content of the snippet.
It is an error if the result of processing a hybrid snippet as an
inline snippet does not match the result of processing it as an external
snippet.
Markup tags
Markup tags define regions within the content of a snippet. They also
control the presentation of the content, for example highlighting parts
of the text, modifying the text, or linking to elsewhere in the
documentation. They can be used in internal, external, and hybrid
snippets.
Markup tags begin with @name, followed by any
required arguments. They are placed in // comments (or the
equivalent in other languages or formats), so as not to unduly interfere
with the body of the source code, and also because
/* ... */ comments cannot be used in inline snippets. Such
comments are referred to as markup comments.
Multiple markup tags can be placed in the same markup comment. The
markup tags apply to the source line containing the comment unless the
comment is terminated with a colon (:), in which case it is
as if the tags were present on the immediately following line. The
latter syntax may be useful if the markup comment is particularly long,
or if the syntactic format of the content of a snippet does not permit
comments to appear on the same line as non-comment source. Markup
comments do not appear in the generated output.
Because some other systems use meta-comments similar to markup
comments, comments that begin with @ followed by an
unrecognized name are ignored as markup comments and will appear in the
generated output. If the name is recognized, but there are subsequent
errors in the markup comment, then an error is reported. The generated
output in such cases is undefined, with respect to the output generated
from the snippet.
Regions
A region is an optionally-named range of lines that identifies the
text to be displayed by a snippet. They also define the scope of actions
such as highlighting or modifying the text.
The beginning of a region is marked by either
@start region=name, or
an @highlight, @replace, or
@link tag that specifies region or
region=name. You can omit the name if it is not
needed by the matching @end tag.
The end of a region is marked by @end or
@end region=name. If a name is given then the tag
ends the region started with that name. If no name is given then the tag
ends the most recently started region that does not already have a
matching @end tag.
There are no constraints on the regions created by different pairs of
matching @start and @end tags. Regions can
even overlap, although we do not expect such usage to be common.
Highlighting
@highlight — highlight text within a line or region
substring — the literal text to be highlighted
regex — a regular expression for the text to be
highlighted
region — a region to define the scope in which to find
the text to be highlighted
type — the type of highlighting, such as
bold, italic, or highlighted
To highlight content on a line or in a range of lines, use
@highlight followed by arguments that specify the scope of
the text to be considered, the text within that scope to be highlighted,
and the type of the highlighting.
If region or region=name is
specified then the scope is that region, up to the corresponding
@end tag. Otherwise, the scope is just the current
line.
To highlight each instance of a literal string within the scope,
specify the string with substring=string where
string can be an identifier or text enclosed in single or
double quotes. To highlight each instance of text matched by a regular
expression within the scope, use regex=string. If
neither of these attributes are specified then the entire scope is
highlighted.
The type of highlighting can be specified with the type
parameter. Valid type names are bold, italic,
and highlighted. The name of the type is converted to a CSS
class name whose properties can be defined in the system stylesheet or
overridden in a user-defined stylesheet.
Modifying the displayed text
@replace — replace text within a line or region
substring — the literal text to be replaced
regex — a regular expression for the text to be
replaced
region — a region to define the scope in which to find
the text to be replaced
replacement — the replacement text
It is often convenient to write the content of a snippet as code that
can be accessed and validated by external tools, but to display it in a
form that does not compile. For example, it may be desirable to include
import statements for illustrative purposes along with code
that uses the imported types. Or, it may be desirable to display code
with an ellipsis or some other marker to indicate that additional code
should be inserted at that point. This can be done by replacing parts of
the content of the snippet with some replacement text.
To replace some text with replacement text, use @replace
followed by arguments that specify the scope of the text to be
considered, the text within that scope to be replaced, and the
replacement text.
If region or region=name is
specified then the scope is that region, up to the corresponding
@end tag. Otherwise, the scope is just the current
line.
To replace each instance of a literal string within the scope,
specify the string with substring=string where
string can be an identifier or text enclosed in single or
double quotes. To replace each instance of text matched by a regular
expression within the scope, use regex=string. If
neither of these attributes are specified then the entire scope is
replaced.
Specify the replacement text with the replacement
parameter. If a regular expression is used to specify the text to be
replaced then $number or
$name can be used to substitute groups found in
the regular expression, as defined by String::replaceAll.
To delete text, use @replace with an empty replacement
string. To insert text, use @replace to replace some no-op
text placed where the replacement text should be inserted. The no-op
text might be a '//' marker, or an empty statement (;).
Linking text
@link — link text within a line or region
substring — the literal text to be linked
regex — a regular expression for the text to be
linked
region — a region to define the scope in which to find
the text to be linked
target — the target of the link, expressed in one of
the forms suitable for a link tag
type — the type of link: one of link (the
default) or linkplain
To link text to declarations elsewhere in the API, use
@link followed by arguments that specify the scope of the
text to be considered, the text within that scope to be linked, and the
target of the link.
If region or region=name is
specified then the scope is that region, up to the corresponding
@end tag. Otherwise, the scope is just the current
line.
To link each instance of a literal string within the scope, specify
the string with substring=string where
string can be an identifier or text enclosed in single or
double quotes. To link each instance of text matched by a regular
expression within the scope, use regex=string. If
neither of these attributes are specified then the entire scope is
linked.
Specify the target with the target parameter. The form
of its value is the same as used by the standard inline
link tag.
Introduced in JDK 18.
spec
@specURLtitle
Identifies an external specification in terms of its URL and title.
The URL may be absolute or relative. Relative URLs will be evaluated
against a "base URL".
All tags specifying the same URL must provide the same corresponding
title; conversely, tags with different URLs must have different
titles.
Introduced in JDK 20.
summary
{@summarytext}
Identify the summary of an API description, as an alternative to the
default policy to identify and use the first sentence of the API
description. The tag only has significance when used at the beginning of
a main description. In all cases, the tag is rendered by simply
rendering its content.
Introduced in JDK 10.
systemProperty
{@systemPropertyproperty-name}
Identify property-name as the name of a system property. The
name should be a "dotted identifier". In particular, it must not contain
whitespace characters, or characters such as }. No other
content is permitted in the tag; the possibility of additional content
is reserved for future use. The tag can be used in all documentation
comments.
Introduced in JDK 12.
throws
@throwsexception-namedescription
Adds an exception with the specified name followed by the specified
description to the "Throws" section of a Method or Constructor
detail.
exception-name should refer to an
exception that might be thrown by the method, and should either be the
name of an exception class or a type variable. This tag is valid only in
the documentation comment for a method or constructor.
A documentation comment may use multiple throws tags for
the same or different exceptions. If such a comment is then targeted by
an inheritDoc tag, it copies all exceptions of that kind
into the "Throws" section.
Note: An unchecked exception class may be omitted from the
throws clause, and so won't be considered missing in a
method documentation. To inherit a description of such an exception, add
a corresponding throws tag with an inheritDoc
tag in its description.
To ensure that all checked exceptions are documented, when a
throws tag does not exist for an exception in the
throws clause, the standard doclet adds that exception to
the generated output (with no description) as if it were documented with
the throws tag.
The exception tag is equivalent
to this tag, although using a throws tag is now
recommended.
Introduced in JDK 1.2.
uses
@usesservice-typedescription
This tag may only appear in the documentation comment for a module
declaration, and serves to document that a service may be used by the
module. The description may be used to specify the characteristics of
the service that may be required, and what the module will do if no
provider for the service is available.
Introduced in JDK 9.
value
{@valueformatfield-reference}
Displays the value of a static field with a compile-time constant
value.
The format string may be omitted, in which case a default format will
be used, appropriate to the type of the field. If the format string is
given, it must either begin with a percent character (%) or
be enclosed in double-quote characters ("). It must contain
exactly one percent character. The string must conform to the definition
of a format string, as specified in the documentation for java.util.Formatter.
The conversion specified in the format string must be appropriate for
the type of the constant value.
When the value tag is used without a
field_reference argument in the documentation comment of a
static field, it displays the value of that constant:
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
When used with a field-reference
argument in any documentation comment, the value tag
displays the value of the specified constant:
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {}
Introduced in JDK 1.4; format added in JDK 20.
version
@versionversion-text
Adds a "Version" subheading with the specified version-text
value to the generated documents when the -version option is used. This
tag is intended to hold the current release number of the software that
this code is part of, as opposed to the since tag, which
holds the release number where this code was introduced. The
version-text value has no special internal structure.
A documentation comment can contain multiple version
tags. When it makes sense, you can specify one release number per
version tag or multiple release numbers per tag. In the
former case, the standard doclet inserts a comma (,) and a
space between the names. In the latter case, the entire text is copied
to the generated document without being parsed. Therefore, you can use
multiple names per line when you want a localized separator other than a
comma.
If there are no version tags in the description for a
member class or interface, the standard doclet will (recursively) look
for any such tags in the enclosing class or interface.
Introduced in JDK 1.0.
Where Tags Can Be Used
The following table summarizes which tags can be used in which
contexts.
Methods includes members of annotation interfaces.
Fields includes members of enum classes.
Other includes the Overview page, which is not tied to any
declaration, and HTML and Markdown files in doc-files
subdirectories of a module or package directory. The Overview page is
typically specified with an option to the javadoc
command.
The serialData tag can only be used in the
documentation comment for the readObject,
writeObject, readExternal,
writeExternal, readResolve and
writeReplace methods.
The serialField tag can only be used in the
documentation comment for the serialPersistentFields
field.