\f[R] element.
If the file is a Markdown file, the entire content of the file is used.
.PP
The title on the overview page is set by \f[CR]\-doctitle\f[R].
.PP
\f[I]Note:\f[R] older versions of the \f[CR]javadoc\f[R] tool assumed
that any use of this option was for an HTML file, and allowed any
extension for the \f[I]filename\f[R].
.RE
.TP
\f[CR]\-serialwarn\f[R]
Reports compile\-time warnings for missing \f[CR]\[at]serial\f[R] tags.
By default, Javadoc reports no serial warnings.
Use this option to display the serial warnings, which helps to properly
document default serializable fields and \f[CR]writeExternal\f[R]
methods.
.TP
\f[CR]\-\-since\f[R] \f[I]release\f[R](\f[CR],\f[R]\f[I]release\f[R])*
Generates documentation for APIs that were added or newly deprecated in
the specified \f[I]release\f[R]s.
.RS
.PP
If the \f[CR]\[at]since\f[R] tag in the \f[CR]javadoc\f[R] comment of an
element in the documented source code matches a \f[I]release\f[R] passed
as the option argument, information about the element and the release it
was added in is included in a \[dq]New API\[dq] page.
.PP
If the \[dq]Deprecated API\[dq] page is generated and the
\f[CR]since\f[R] element of the \f[CR]java.lang.Deprecated\f[R]
annotation of a documented element matches a \f[I]release\f[R] in the
option arguments, information about the release the element was
deprecated in is added to the \[dq]Deprecated API\[dq] page.
.PP
Releases are compared using case\-sensitive string comparison.
.RE
.TP
\f[CR]\-\-since\-label\f[R] \f[I]text\f[R]
Specifies the \f[I]text\f[R] to use in the heading of the \[dq]New
API\[dq] page.
This may contain information about the releases covered in the page,
e.g.
\[dq]New API in release 2.0\[dq], or \[dq]New API since release 1\[dq].
.TP
\f[CR]\-\-snippet\-path\f[R] \f[I]snippetpathlist\f[R]
Specifies the search paths for finding files for external snippets.
The \f[I]snippetpathlist\f[R] can contain multiple paths by separating
them with the platform path separator (\f[CR];\f[R] on Windows;
\f[CR]:\f[R] on other platforms.)
The standard doclet first searches the \f[CR]snippet\-files\f[R]
subdirectory in the package containing the snippet, and then searches
all the directories in the given list.
.TP
\f[CR]\-sourcetab\f[R] \f[I]tab\-length\f[R]
Specifies the number of spaces each tab uses in the source.
.TP
\f[CR]\-\-spec\-base\-url\f[R] \f[I]url\f[R]
Specifies the base URL for relative URLs in \f[CR]\[at]spec\f[R] tags,
to be used when generating links to any external specifications.
It can either be an absolute URL, or a relative URL, in which case it is
evaluated relative to the base directory of the generated output files.
The default value is equivalent to \f[CR]{\[at]docRoot}/../specs\f[R].
.TP
\f[CR]\-splitindex\f[R]
Splits the index file into multiple files, alphabetically, one file per
letter, plus a file for any index entries that start with
non\-alphabetical symbols.
.TP
\f[CR]\-\-syntax\-highlight\f[R]
Enables syntax highlighting for code fragments in
\f[CR]{\[at]snippet}\f[R] tags and \f[CR]\f[R] elements.
For snippets, the \f[CR]lang\f[R] attribute is used to determine the
language of code fragments, which defaults to \[dq]java\[dq] for inline
snippets and is derived from the file extension for external snippets.
In HTML \f[CR]\f[R] tags, the \f[CR]class\f[R] attribute can
be used to specify the language of the contained code fragment as shown
below:
.RS
.IP
.EX
...
.EE
.PP
If neither of these attributes is available automatic language detection
is applied.
To disable syntax highlighting for a code fragment set the language to
\[dq]text\[dq] using one of the mechanisms described above.
The languages and formats supported by this option are Java, Properties,
JSON, HTML and XML.
.RE
.TP
\f[CR]\-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
Specifies a custom tag with a single argument.
For the \f[CR]javadoc\f[R] tool to spell\-check tag names, it is
important to include a \f[CR]\-tag\f[R] option for every custom tag that
is present in the source code, disabling (with \f[CR]X\f[R]) those that
aren\[aq]t being output in the current run.
The colon (\f[CR]:\f[R]) is always the separator.
To include a colon in the tag name, escape it with a backward slash
(\f[CR]\[rs]\f[R]).
The \f[CR]\-tag\f[R] option outputs the tag heading, \f[I]header\f[R],
in bold, followed on the next line by the text from its single argument.
Similar to any block tag, the argument text can contain inline tags,
which are also interpreted.
The output is similar to standard one\-argument tags, such as the
\f[CR]\[at]return\f[R] and \f[CR]\[at]author\f[R] tags.
Omitting a \f[I]header\f[R] value causes the \f[I]name\f[R] to be the
heading.
\f[I]locations\f[R] is a list of characters specifying the kinds of
declarations in which the tag may be used.
The following characters may be used, in either uppercase or lowercase:
.RS
.IP \[bu] 2
\f[CR]A\f[R]: all declarations
.IP \[bu] 2
\f[CR]C\f[R]: constructors
.IP \[bu] 2
\f[CR]F\f[R]: fields
.IP \[bu] 2
\f[CR]M\f[R]: methods
.IP \[bu] 2
\f[CR]O\f[R]: the overview page and other documentation files in
\f[CR]doc\-files\f[R] subdirectories
.IP \[bu] 2
\f[CR]P\f[R]: packages
.IP \[bu] 2
\f[CR]S\f[R]: modules
.IP \[bu] 2
\f[CR]T\f[R]: types (classes and interfaces)
.IP \[bu] 2
\f[CR]X\f[R]: nowhere: the tag is disabled, and will be ignored
.PP
The order in which tags are given on the command line will be used as
the order in which the tags appear in the generated output.
You can include standard tags in the order given on the command line by
using the \f[CR]\-tag\f[R] option with no \f[I]locations\f[R] or
\f[I]header\f[R].
.RE
.TP
\f[CR]\-taglet\f[R] \f[I]class\f[R]
Specifies the fully qualified name of the taglet used in generating the
documentation for that tag.
Use the fully qualified name for the \f[I]class\f[R] value.
This taglet also defines the number of text arguments that the custom
tag has.
The taglet accepts those arguments, processes them, and generates the
output.
.RS
.PP
Taglets are useful for block or inline tags.
They can have any number of arguments and implement custom behavior,
such as making text bold, formatting bullets, writing out the text to a
file, or starting other processes.
Taglets can only determine where a tag should appear and in what form.
All other decisions are made by the doclet.
A taglet can\[aq]t do things such as remove a class name from the list
of included classes.
However, it can execute side effects, such as printing the tag\[aq]s
text to a file or triggering another process.
Use the \f[CR]\-tagletpath\f[R] option to specify the path to the
taglet.
The following example inserts the To Do taglet after Parameters and
ahead of Throws in the generated pages.
.IP
.EX
\-taglet com.sun.tools.doclets.ToDoTaglet
\-tagletpath /home/taglets
\-tag return
\-tag param
\-tag todo
\-tag throws
\-tag see
.EE
.PP
Alternately, you can use the \f[CR]\-taglet\f[R] option in place of its
\f[CR]\-tag\f[R] option, but that might be difficult to read.
.RE
.TP
\f[CR]\-tagletpath\f[R] \f[I]tagletpathlist\f[R]
Specifies the search paths for finding taglet class files.
The \f[I]tagletpathlist\f[R] can contain multiple paths by separating
them with the platform path separator (\f[CR];\f[R] on Windows;
\f[CR]:\f[R] on other platforms.)
The \f[CR]javadoc\f[R] tool searches all subdirectories of the specified
paths.
.TP
\f[CR]\-top\f[R] \f[I]html\-code\f[R]
Specifies the text to be placed at the top of each output file.
.TP
\f[CR]\-use\f[R]
Creates class and package usage pages.
Includes one Use page for each documented class and package.
The page describes what packages, classes, methods, constructors, and
fields use any API of the specified class or package.
Given class C, things that use class C would include subclasses of C,
fields declared as C, methods that return C, and methods and
constructors with parameters of type C. For example, you can look at the
Use page for the \f[CR]String\f[R] type.
Because the \f[CR]getName\f[R] method in the \f[CR]java.awt.Font\f[R]
class returns type \f[CR]String\f[R], the \f[CR]getName\f[R] method uses
\f[CR]String\f[R] and so the \f[CR]getName\f[R] method appears on the
Use page for \f[CR]String\f[R].
This documents only uses of the API, not the implementation.
When a method uses \f[CR]String\f[R] in its implementation, but
doesn\[aq]t take a string as an argument or return a string, that
isn\[aq]t considered a use of \f[CR]String\f[R].
To access the generated Use page, go to the class or package and click
the \f[B]USE\f[R] link in the navigation bar.
.TP
\f[CR]\-version\f[R]
Includes the text of any \f[CR]version\f[R] tags in the generated
documentation.
This text is omitted by default.
Note: To find out what version of the \f[CR]javadoc\f[R] tool you are
using, use the \f[CR]\-\-version\f[R] option (with two hyphens).
.TP
\f[CR]\-windowtitle\f[R] \f[I]title\f[R]
Specifies the title to be placed in the HTML \f[CR]\f[R] tag.
The text specified in the \f[CR]title\f[R] tag appears in the window
title and in any browser bookmarks (favorite places) that someone
creates for this page.
This title should not contain any HTML tags because a browser will not
interpret them correctly.
Use escape characters on any internal quotation marks within the
\f[CR]title\f[R] tag.
If the \f[CR]\-windowtitle\f[R] option is omitted, then the
\f[CR]javadoc\f[R] tool uses the value of the \f[CR]\-doctitle\f[R]
option for the \f[CR]\-windowtitle\f[R] option.
For example,
\f[CR]javadoc \-windowtitle \[dq]My Library\[dq] com.mypackage\f[R].
.SS Extra Options for the Standard Doclet
The following are additional options provided by the standard doclet and
are subject to change without notice.
Additional options are less commonly used or are otherwise regarded as
advanced.
.TP
\f[CR]\-\-date\f[R] \f[I]date\-and\-time\f[R]
Specifies the value to be used to timestamp the generated pages, in
\f[B]ISO 8601\f[R]
[https://www.iso.org/iso\-8601\-date\-and\-time\-format.html] format.
The specified value must be within 10 years of the current date and
time.
It is an error to specify both \f[CR]\-notimestamp\f[R] and
\f[CR]\-\-date\f[R].
Using a specific value means the generated documentation can be part of
a \f[B]reproducible build\f[R] [https://reproducible\-builds.org/].
If the option is not given, the default value is the current date and
time.
For example:
.RS
.IP
.EX
javadoc \-\-date 2022\-02\-01T17:41:59\-08:00 mypackage
.EE
.RE
.TP
\f[CR]\-\-legal\-notices\f[R] (\f[CR]default\f[R]|\f[CR]none\f[R]|\f[I]directory\f[R])
Specifies the location from which to copy legal files to the generated
documentation.
If the option is not specified or is used with the value
\f[CR]default\f[R], the files are copied from the default location.
If the argument is used with value \f[CR]none\f[R], no files are copied.
Every other argument is interpreted as directory from which to copy the
legal files.
.TP
\f[CR]\-\-no\-frames\f[R]
This option is no longer supported and reports a warning.
.TP
\f[CR]\-Xdoclint\f[R]
Enables recommended checks for problems in documentation comments.
.RS
.PP
By default, the \f[CR]\-Xdoclint\f[R] option is enabled.
Disable it with the option \f[CR]\-Xdoclint:none\f[R].
.PP
For more details, see \f[B]DocLint\f[R].
.RE
.TP
\f[CR]\-Xdoclint:\f[R]\f[I]flag\f[R],\f[I]flag\f[R],...
Enables or disables specific checks for different kinds of issues in
documentation comments.
.RS
.PP
Each \f[I]flag\f[R] can be one of \f[CR]all\f[R], \f[CR]none\f[R], or
\f[CR][\-]\f[R]\f[I]group\f[R] where \f[I]group\f[R] has one of the
following values: \f[CR]accessibility\f[R], \f[CR]html\f[R],
\f[CR]missing\f[R], \f[CR]reference\f[R], \f[CR]syntax\f[R].
For more details on these values, see \f[B]DocLint Groups\f[R].
.PP
When specifying two or more flags, you can either use a single
\f[CR]\-Xdoclint:...\f[R] option, listing all the desired flags, or you
can use multiple options giving one or more flag in each option.
For example, use either of the following commands to check for the HTML,
syntax, and accessibility issues in the file \f[CR]MyFile.java\f[R].
.IP
.EX
javadoc \-Xdoclint:html \-Xdoclint:syntax \-Xdoclint:accessibility MyFile.java
javadoc \-Xdoclint:html,syntax,accessibility MyFile.java
.EE
.PP
The following examples illustrate how to change what DocLint reports:
.IP \[bu] 2
\f[CR]\-Xdoclint:none\f[R] \-\-\- disables all checks
.IP \[bu] 2
\f[CR]\-Xdoclint:\f[R]\f[I]group\f[R] \-\-\- enables \f[I]group\f[R]
checks
.IP \[bu] 2
\f[CR]\-Xdoclint:all\f[R] \-\-\- enables all groups of checks
.IP \[bu] 2
\f[CR]\-Xdoclint:all,\-\f[R]\f[I]group\f[R] \-\-\- enables all checks
except \f[I]group\f[R] checks
.PP
For more details, see \f[B]DocLint\f[R].
.RE
.TP
\f[CR]\-Xdoclint/package:\f[R][\f[CR]\-\f[R]]\f[I]packages\f[R]
Enables or disables checks in specific packages.
\f[I]packages\f[R] is a comma separated list of package specifiers.
A package specifier is either a qualified name of a package or a package
name prefix followed by \f[CR]*\f[R], which expands to all subpackages
of the given package.
Prefix the package specifier with \f[CR]\-\f[R] to disable checks for
the specified packages.
.RS
.PP
For more details, see \f[B]DocLint\f[R].
.RE
.TP
\f[CR]\-Xdocrootparent\f[R] \f[I]url\f[R]
Replaces all \f[CR]\[at]docRoot\f[R] items followed by \f[CR]/..\f[R] in
documentation comments with \f[I]url\f[R].
.SH DOCLINT
DocLint provides the ability to check for possible problems in
documentation comments.
Problems may be reported as warnings or errors, depending on their
severity.
For example, a missing comment may be bad style that deserves a warning,
but a link to an unknown Java declaration is more serious and deserves
an error.
Problems are organized into \f[B]groups\f[R], and options can be used to
enable or disable messages in one or more groups.
Within the source code, messages in one or more groups can be
\f[B]suppressed\f[R] by using \f[CR]\[at]SuppressWarnings\f[R]
annotations.
.PP
When invoked from \f[CR]javadoc\f[R], by default DocLint checks all
comments that are used in the generated documentation.
It thus relies on other command\-line options to determine which
declarations, and which corresponding documentation comments will be
included.
\f[I]Note:\f[R] this may mean that even comments on some private members
of serializable classes will also be checked, if the members need to be
documented in the generated \f[CR]Serialized Forms\f[R] page.
.PP
In contrast, when DocLint is invoked from \f[CR]javac\f[R], DocLint
solely relies on the various \f[CR]\-Xdoclint...\f[R] options to
determine which documentation comments to check.
.PP
DocLint doesn\[aq]t attempt to fix invalid input, it just reports it.
.PP
\f[I]Note:\f[R] DocLint doesn\[aq]t guarantee the completeness of these
checks.
In particular, it isn\[aq]t a full HTML compliance checker.
The goal is to just report common errors in a convenient manner.
.SS Groups
The checks performed by DocLint are organized into groups.
The warnings and errors in each group can be enabled or disabled with
command\-line options, or suppressed with
\f[CR]\[at]SuppressWarnings\f[R] annotations.
.PP
The groups are as follows:
.IP \[bu] 2
\f[CR]accessibility\f[R] \-\-\- Checks for issues related to
accessibility.
For example, no \f[CR]alt\f[R] attribute specified in an
\f[CR]<img>\f[R] element, or no caption or summary attributes specified
in a \f[CR]<table>\f[R] element.
.RS 2
.PP
Issues are reported as errors if a downstream validation tool might be
expected to report an error in the files generated by
\f[CR]javadoc\f[R].
.PP
For reference, see the \f[B]Web Content Accessibility Guidelines\f[R]
[https://www.w3.org/WAI/standards\-guidelines/wcag/].
.RE
.IP \[bu] 2
\f[CR]html\f[R] \-\-\- Detects common high\-level HTML issues.
For example, putting block elements inside inline elements, or not
closing elements that require an end tag.
.RS 2
.PP
Issues are reported as errors if a downstream validation tool might be
expected to report an error in the files generated by
\f[CR]javadoc\f[R].
.PP
For reference, see the \f[B]HTML Living Standard\f[R]
[https://html.spec.whatwg.org/multipage/].
.RE
.IP \[bu] 2
\f[CR]missing\f[R] \-\-\- Checks for missing documentation comments or
tags.
For example, a missing comment on a class declaration, or a missing
\f[CR]\[at]param\f[R] or \f[CR]\[at]return\f[R] tag in the comment for a
method declaration.
.RS 2
.PP
Issues related to missing items are typically reported as warnings
because they are unlikely to be reported as errors by downstream
validation tools that may be used to check the output generated by
\f[CR]javadoc\f[R].
.RE
.IP \[bu] 2
\f[CR]reference\f[R] \-\-\- Checks for issues relating to the references
to Java API elements from documentation comment tags.
For example, the reference in \f[CR]\[at]see\f[R] or
\f[CR]{\[at]link ...}\f[R] cannot be found, or a bad name is given for
\f[CR]\[at]param\f[R] or \f[CR]\[at]throws\f[R].
.RS 2
.PP
Issues are typically reported as errors because while the issue may not
cause problems in the generated files, the author has likely made a
mistake that will lead to incorrect or unexpected documentation.
.RE
.IP \[bu] 2
\f[CR]syntax\f[R] \-\-\- Checks for low\-level syntactic issues in
documentation comments.
For example, unescaped angle brackets (\f[CR]<\f[R] and \f[CR]>\f[R])
and ampersands (\f[CR]&\f[R]) and invalid documentation comment tags.
.RS 2
.PP
Issues are typically reported as errors because the issues may lead to
incorrect or unexpected documentation.
.RE
.SS Suppressing Messages
DocLint checks for and recognizes two strings that may be present in the
arguments for an \f[CR]\[at]SuppressWarnings\f[R] annotation.
.IP \[bu] 2
\f[CR]doclint\f[R]
.IP \[bu] 2
\f[CR]doclint:\f[R]\f[I]LIST\f[R]
.PP
where \f[I]LIST\f[R] is a comma\-separated list of one or more of
\f[CR]accessibility\f[R], \f[CR]html\f[R], \f[CR]missing\f[R],
\f[CR]reference\f[R], \f[CR]syntax\f[R].
.PP
The names in \f[I]LIST\f[R] are the same \f[B]group\f[R] names supported
by the command\-line \f[CR]\-Xdoclint\f[R] option for \f[CR]javac\f[R]
and \f[CR]javadoc\f[R].
(This is the same convention honored by the \f[CR]javac\f[R]
\f[CR]\-Xlint\f[R] option and the corresponding names supported by
\f[CR]\[at]SuppressWarnings\f[R].)
.PP
The names in \f[I]LIST\f[R] can equivalently be specified in separate
arguments of the annotation.
For example, the following are equivalent:
.IP \[bu] 2
\f[CR]\[at]SuppressWarnings(\[dq]doclint:accessibility,missing\[dq])\f[R]
.IP \[bu] 2
\f[CR]\[at]SuppressWarnings(\[dq]doclint:accessibility\[dq], \[dq]doclint:missing\[dq])\f[R]
.PP
When DocLint detects an issue in a documentation comment, it checks for
the presence of \f[CR]\[at]SuppressWarnings\f[R] on the associated
declaration and on all lexically enclosing declarations.
The issue will be ignored if any such annotation is found containing the
simple string \f[CR]doclint\f[R] or the longer form
\f[CR]doclint:LIST\f[R] where \f[I]LIST\f[R] contains the name of the
group for the issue.
.PP
\f[I]Note:\f[R] as with other uses of \f[CR]\[at]SuppressWarnings\f[R],
using the annotation on a module or package declaration only affects
that declaration; it does not affect the contents of the module or
package in other source files.
.PP
All messages related to an issue are suppressed by the presence of an
appropriate \f[CR]\[at]SuppressWarnings\f[R] annotation: this includes
errors as well as warnings.
.PP
\f[I]Note:\f[R] It is only possible to \f[I]suppress\f[R] messages.
If an annotation of \f[CR]\[at]SuppressWarnings(\[dq]doclint\[dq])\f[R]
is given on a top\-level declaration, all DocLint messages for that
declaration and any enclosed declarations will be suppressed; it is not
possible to selectively re\-enable messages for issues in enclosed
declarations.
.SS Comparison with downstream validation tools
DocLint is a utility built into \f[CR]javac\f[R] and \f[CR]javadoc\f[R]
that checks the content of documentation comments, as found in source
files.
In contrast, downstream validation tools can be used to validate the
output generated from those documentation comments by \f[CR]javadoc\f[R]
and the standard doclet.
.PP
Although there is some overlap in functionality, the two mechanisms are
different and each has its own strengths and weaknesses.
.IP \[bu] 2
Downstream validation tools can check the end result of any generated
documentation, as it will be seen by the end user.
This includes content from all sources, including documentation
comments, the standard doclet itself, user\-provided taglets, and
content supplied via command\-line options.
Because such tools are analyzing complete HTML pages, they can do more
complete checks than can DocLint.
However, when a problem is found in the generated pages, it can be
harder to track down exactly where in the build pipeline the problem
needs to be fixed.
.IP \[bu] 2
DocLint checks the content of documentation comments, in source files.
This makes it very easy to identify the exact position of any issues
that may be found.
DocLint can also detect some semantic errors in documentation comments
that downstream tools cannot detect, such as missing comments, using an
\f[CR]\[at]return\f[R] tag in a method returning \f[CR]void\f[R], or an
\f[CR]\[at]param\f[R] tag describing a non\-existent parameter.
But by its nature, DocLint cannot report on problems such as missing
links, or errors in user\-provided custom taglets, or problems in the
standard doclet itself.
It also cannot reliably detect errors in documentation comments at the
boundaries between content in a documentation comment and content
generated by a custom taglet.