element. If the
file is a Markdown file, the entire content of the file is used.
The title on the overview page is set by -doctitle.
Note: older versions of the javadoc tool assumed that any use of
this option was for an HTML file, and allowed any extension for
the filename.
-serialwarn
Reports compile-time warnings for missing @serial 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 writeExternal methods.
--since release(,release)*
Generates documentation for APIs that were added or newly
deprecated in the specified releases.
If the @since tag in the javadoc comment of an element in the
documented source code matches a release passed as the option
argument, information about the element and the release it was
added in is included in a "New API" page.
If the "Deprecated API" page is generated and the since element
of the java.lang.Deprecated annotation of a documented element
matches a release in the option arguments, information about the
release the element was deprecated in is added to the
"Deprecated API" page.
Releases are compared using case-sensitive string comparison.
--since-label text
Specifies the text to use in the heading of the "New API" page.
This may contain information about the releases covered in the
page, e.g. "New API in release 2.0", or "New API since release
1".
--snippet-path snippetpathlist
Specifies the search paths for finding files for external
snippets. The snippetpathlist can contain multiple paths by
separating them with the platform path separator (; on Windows;
: on other platforms.) The standard doclet first searches the
snippet-files subdirectory in the package containing the
snippet, and then searches all the directories in the given
list.
-sourcetab tab-length
Specifies the number of spaces each tab uses in the source.
--spec-base-url url
Specifies the base URL for relative URLs in @spec 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
{@docRoot}/../specs.
-splitindex
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.
--syntax-highlight
Enables syntax highlighting for code fragments in {@snippet}
tags and elements. For snippets, the lang attribute
is used to determine the language of code fragments, which
defaults to "java" for inline snippets and is derived from the
file extension for external snippets. In HTML tags,
the class attribute can be used to specify the language of the
contained code fragment as shown below:
...
If neither of these attributes is available automatic language
detection is applied. To disable syntax highlighting for a code
fragment set the language to "text" using one of the mechanisms
described above. The languages and formats supported by this
option are Java, Properties, JSON, HTML and XML.
-tag name:locations:header
Specifies a custom tag with a single argument. For the javadoc
tool to spell-check tag names, it is important to include a -tag
option for every custom tag that is present in the source code,
disabling (with X) those that aren't being output in the current
run. The colon (:) is always the separator. To include a colon
in the tag name, escape it with a backward slash (\). The -tag
option outputs the tag heading, header, 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 @return and @author tags.
Omitting a header value causes the name to be the heading.
locations 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:
o A: all declarations
o C: constructors
o F: fields
o M: methods
o O: the overview page and other documentation files in
doc-files subdirectories
o P: packages
o S: modules
o T: types (classes and interfaces)
o X: nowhere: the tag is disabled, and will be ignored
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 -tag option with no locations or
header.
-taglet class
Specifies the fully qualified name of the taglet used in
generating the documentation for that tag. Use the fully
qualified name for the class 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.
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'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's text to a file
or triggering another process. Use the -tagletpath 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.
-taglet com.sun.tools.doclets.ToDoTaglet
-tagletpath /home/taglets
-tag return
-tag param
-tag todo
-tag throws
-tag see
Alternately, you can use the -taglet option in place of its -tag
option, but that might be difficult to read.
-tagletpath tagletpathlist
Specifies the search paths for finding taglet class files. The
tagletpathlist can contain multiple paths by separating them
with the platform path separator (; on Windows; : on other
platforms.) The javadoc tool searches all subdirectories of the
specified paths.
-top html-code
Specifies the text to be placed at the top of each output file.
-use 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 String type. Because the getName method in the
java.awt.Font class returns type String, the getName method uses
String and so the getName method appears on the Use page for
String. This documents only uses of the API, not the
implementation. When a method uses String in its
implementation, but doesn't take a string as an argument or
return a string, that isn't considered a use of String. To
access the generated Use page, go to the class or package and
click the USE link in the navigation bar.
-version
Includes the text of any version tags in the generated
documentation. This text is omitted by default. Note: To find
out what version of the javadoc tool you are using, use the
--version option (with two hyphens).
-windowtitle title
Specifies the title to be placed in the HTML tag. The
text specified in the title 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 title tag.
If the -windowtitle option is omitted, then the javadoc tool
uses the value of the -doctitle option for the -windowtitle
option. For example, javadoc -windowtitle "My Library"
com.mypackage.
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.
--date date-and-time
Specifies the value to be used to timestamp the generated pages,
in ISO 8601
[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 -notimestamp and
--date. Using a specific value means the generated
documentation can be part of a reproducible build
[https://reproducible-builds.org/]. If the option is not given,
the default value is the current date and time. For example:
javadoc --date 2022-02-01T17:41:59-08:00 mypackage
--legal-notices (default|none|directory)
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 default, the files are copied from the
default location. If the argument is used with value none, no
files are copied. Every other argument is interpreted as
directory from which to copy the legal files.
--no-frames
This option is no longer supported and reports a warning.
-Xdoclint
Enables recommended checks for problems in documentation
comments.
By default, the -Xdoclint option is enabled. Disable it with
the option -Xdoclint:none.
For more details, see DocLint.
-Xdoclint:flag,flag,...
Enables or disables specific checks for different kinds of
issues in documentation comments.
Each flag can be one of all, none, or [-]group where group has
one of the following values: accessibility, html, missing,
reference, syntax. For more details on these values, see
DocLint Groups.
When specifying two or more flags, you can either use a single
-Xdoclint:... 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
MyFile.java.
javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility MyFile.java
javadoc -Xdoclint:html,syntax,accessibility MyFile.java
The following examples illustrate how to change what DocLint
reports:
o -Xdoclint:none --- disables all checks
o -Xdoclint:group --- enables group checks
o -Xdoclint:all --- enables all groups of checks
o -Xdoclint:all,-group --- enables all checks except group
checks
For more details, see DocLint.
-Xdoclint/package:[-]packages
Enables or disables checks in specific packages. packages 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 *, which expands to all subpackages of the given
package. Prefix the package specifier with - to disable checks
for the specified packages.
For more details, see DocLint.
-Xdocrootparent url
Replaces all @docRoot items followed by /.. in documentation
comments with url.
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 groups, 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 suppressed by using @SuppressWarnings
annotations.
When invoked from javadoc, 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. Note: 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 Serialized Forms page.
In contrast, when DocLint is invoked from javac, DocLint solely relies
on the various -Xdoclint... options to determine which documentation
comments to check.
DocLint doesn't attempt to fix invalid input, it just reports it.
Note: DocLint doesn't guarantee the completeness of these checks. In
particular, it isn't a full HTML compliance checker. The goal is to
just report common errors in a convenient manner.
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 @SuppressWarnings annotations.
The groups are as follows:
o accessibility --- Checks for issues related to accessibility. For
example, no alt attribute specified in an <img> element, or no
caption or summary attributes specified in a <table> element.
Issues are reported as errors if a downstream validation tool might
be expected to report an error in the files generated by javadoc.
For reference, see the Web Content Accessibility Guidelines
[https://www.w3.org/WAI/standards-guidelines/wcag/].
o html --- Detects common high-level HTML issues. For example, putting
block elements inside inline elements, or not closing elements that
require an end tag.
Issues are reported as errors if a downstream validation tool might
be expected to report an error in the files generated by javadoc.
For reference, see the HTML Living Standard
[https://html.spec.whatwg.org/multipage/].
o missing --- Checks for missing documentation comments or tags. For
example, a missing comment on a class declaration, or a missing
@param or @return tag in the comment for a method declaration.
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
javadoc.
o reference --- Checks for issues relating to the references to Java
API elements from documentation comment tags. For example, the
reference in @see or {@link ...} cannot be found, or a bad name is
given for @param or @throws.
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.
o syntax --- Checks for low-level syntactic issues in documentation
comments. For example, unescaped angle brackets (< and >) and
ampersands (&) and invalid documentation comment tags.
Issues are typically reported as errors because the issues may lead
to incorrect or unexpected documentation.
Suppressing Messages
DocLint checks for and recognizes two strings that may be present in
the arguments for an @SuppressWarnings annotation.
o doclint
o doclint:LIST
where LIST is a comma-separated list of one or more of accessibility,
html, missing, reference, syntax.
The names in LIST are the same group names supported by the
command-line -Xdoclint option for javac and javadoc. (This is the same
convention honored by the javac -Xlint option and the corresponding
names supported by @SuppressWarnings.)
The names in LIST can equivalently be specified in separate arguments
of the annotation. For example, the following are equivalent:
o @SuppressWarnings("doclint:accessibility,missing")
o @SuppressWarnings("doclint:accessibility", "doclint:missing")
When DocLint detects an issue in a documentation comment, it checks for
the presence of @SuppressWarnings 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 doclint or the
longer form doclint:LIST where LIST contains the name of the group for
the issue.
Note: as with other uses of @SuppressWarnings, 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.
All messages related to an issue are suppressed by the presence of an
appropriate @SuppressWarnings annotation: this includes errors as well
as warnings.
Note: It is only possible to suppress messages. If an annotation of
@SuppressWarnings("doclint") 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.
Comparison with downstream validation tools
DocLint is a utility built into javac and javadoc 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 javadoc and the
standard doclet.
Although there is some overlap in functionality, the two mechanisms are
different and each has its own strengths and weaknesses.
o 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.
o 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 @return tag in a method returning
void, or an @param 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.
JDK 25.0.1 2025 JAVADOC(1)