JAVADOC(1) JDK Commands JAVADOC(1) NAME javadoc - generate HTML pages of API documentation from Java source files SYNOPSIS javadoc [options] [packagenames] [sourcefiles] [@files] options Specifies command-line options, separated by spaces. See Standard javadoc Options, Extra javadoc Options, Standard Options for the Standard Doclet, and Extra Options for the Standard Doclet. packagenames Specifies names of packages that you want to document, separated by spaces, for example java.lang java.lang.reflect java.awt. If you want to also document the subpackages, then use the -subpackages option to specify the packages. By default, javadoc looks for the specified packages in the current directory and subdirectories. Use the -sourcepath option to specify the list of directories where to look for packages. sourcefiles Specifies names of Java source files that you want to document, separated by spaces, for example Class.java Object.java Button.java. By default, javadoc looks for the specified classes in the current directory. However, you can specify the full path to the class file and use wildcard characters, for example /home/src/java/awt/Graphics*.java. You can also specify the path relative to the current directory. @files Specifies names of files that contain a list of javadoc tool options, package names, and source file names in any order. DESCRIPTION The javadoc tool parses the declarations and documentation comments in a set of Java source files and produces corresponding HTML pages that describe (by default) the public and protected classes, nested and implicitly declared classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use the javadoc tool to generate the API documentation or the implementation documentation for a set of source files. You can run the javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can use the -subpackages option either to recursively traverse a directory and its subdirectories, or to pass in an explicit list of package names. When you document individual source files, pass in a list of Java source file names. Conformance The Standard Doclet does not validate the content of documentation comments for conformance, nor does it attempt to correct any errors in documentation comments. Anyone running javadoc is advised to be aware of the problems that may arise when generating non-conformant output or output containing executable content, such as JavaScript. The Standard Doclet does provide the DocLint feature to help developers detect common problems in documentation comments; but it is also recommended to check the generated output with any appropriate conformance and other checking tools. For more details on the conformance requirements for HTML5 documents, see Conformance requirements [https://www.w3.org/TR/html5/infrastructure.html#conformance- requirements] in the HTML5 Specification. For more details on security issues related to web pages, see the Open Web Application Security Project (OWASP) [https://www.owasp.org] page. OPTIONS javadoc supports command-line options for both the main javadoc tool and the currently selected doclet. The Standard Doclet is used if no other doclet is specified. GNU-style options (that is, those beginning with --) can use an equal sign (=) instead of whitespace characters to separate the name of an option from its value. Standard javadoc Options The following core javadoc options are equivalent to corresponding javac options. See Standard Options in javac for the detailed descriptions of using these options: o --add-modules o -bootclasspath o --class-path, -classpath, or -cp o --enable-preview o -encoding o -extdirs o --limit-modules o --module o --module-path or -p o --module-source-path o --release o --source or -source o --source-path or -sourcepath o --system o --upgrade-module-path The following options are the core javadoc options that are not equivalent to a corresponding javac option: -breakiterator Computes the first sentence with BreakIterator. The first sentence is copied to the package, class, or member summary and to the alphabetic index. The BreakIterator class is used to determine the end of a sentence for all languages except for English. o English default sentence-break algorithm --- Stops at a period followed by a space or an HTML block tag, such as
.
o Breakiterator sentence-break algorithm --- Stops at a period,
question mark, or exclamation point followed by a space when
the next word starts with a capital letter. This is meant to
handle most abbreviations (such as "The serial no. is valid",
but will not handle "Mr. Smith"). The -breakiterator option
doesn't stop at HTML tags or sentences that begin with numbers
or symbols. The algorithm stops at the last period in
../filename, even when embedded in an HTML tag.
-doclet class
Generates output by using an alternate doclet. Use the fully
qualified name. This doclet defines the content and formats the
output. If the -doclet option isn't used, then the javadoc tool
uses the standard doclet for generating the default HTML format.
This class must contain the start(Root) method. The path to
this starting class is defined by the -docletpath option.
-docletpath path
Specifies where to find doclet class files (specified with the
-doclet option) and any JAR files it depends on. If the
starting class file is in a JAR file, then this option specifies
the path to that JAR file. You can specify an absolute path or
a path relative to the current directory. If classpathlist
contains multiple paths or JAR files, then they should be
separated with a colon (:) on Linux and a semi-colon (;) on
Windows. This option isn't necessary when the doclet starting
class is already in the search path.
-exclude pkglist
Unconditionally, excludes the specified packages and their
subpackages from the list formed by -subpackages. It excludes
those packages even when they would otherwise be included by
some earlier or later -subpackages option.
The following example would include java.io, java.util, and
java.math (among others), but would exclude packages rooted at
java.net and java.lang. Notice that these examples exclude
java.lang.ref, which is a subpackage of java.lang.
o Linux and macOS:
javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
o Windows:
javadoc -sourcepath \user\src -subpackages java -exclude java.net:java.lang
--expand-requires value
Instructs the javadoc tool to expand the set of modules to be
documented. By default, only the modules given explicitly on
the command line are documented. Supports the following values:
o transitive: additionally includes all the required transitive
dependencies of those modules.
o all: includes all dependencies.
--help, -help, -h, or -?
Prints a synopsis of the standard options.
--help-extra or -X
Prints a synopsis of the set of extra options.
-Jflag Passes flag directly to the Java Runtime Environment (JRE) that
runs the javadoc tool. For example, if you must ensure that the
system sets aside 32 MB of memory in which to process the
generated documentation, then you would call the -Xmx option as
follows: javadoc -J-Xmx32m -J-Xms32m com.mypackage. Be aware
that -Xms is optional because it only sets the size of initial
memory, which is useful when you know the minimum amount of
memory required.
There is no space between the J and the flag.
Use the -version option to report the version of the JRE being
used to run the javadoc tool.
javadoc -J-version
java version "17" 2021-09-14 LTS
Java(TM) SE Runtime Environment (build 17+35-LTS-2724)
Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)
-locale name
Specifies the locale that the javadoc tool uses when it
generates documentation. The argument is the name of the
locale, as described in java.util.Locale documentation, such as
en_US (English, United States) or en_US_WIN (Windows variant).
Specifying a locale causes the javadoc tool to choose the
resource files of that locale for messages such as strings in
the navigation bar, headings for lists and tables, help file
contents, comments in the stylesheet.css file, and so on. It
also specifies the sorting order for lists sorted
alphabetically, and the sentence separator to determine the end
of the first sentence. The -locale option doesn't determine the
locale of the documentation comment text specified in the source
files of the documented classes.
-package
Shows only package, protected, and public classes and members.
-private
Shows all classes and members.
-protected
Shows only protected and public classes and members. This is
the default.
-public
Shows only the public classes and members.
-quiet Shuts off messages so that only the warnings and errors appear
to make them easier to view. It also suppresses the version
string.
--show-members value
Specifies which members (fields or methods) are documented,
where value can be any of the following:
o public --- shows only public members
o protected --- shows public and protected members; this is the
default
o package --- shows public, protected, and package members
o private --- shows all members
--show-module-contents value
Specifies the documentation granularity of module declarations,
where value can be api or all.
--show-packages value
Specifies which modules packages are documented, where value can
be exported or all packages.
--show-types value
Specifies which types (classes, interfaces, etc.) are
documented, where value can be any of the following:
o public --- shows only public types
o protected --- shows public and protected types; this is the
default
o package --- shows public, protected, and package types
o private --- shows all types
-subpackages subpkglist
Generates documentation from source files in the specified
packages and recursively in their subpackages. This option is
useful when adding new subpackages to the source code because
they are automatically included. Each package argument is any
top-level subpackage (such as java) or fully qualified package
(such as javax.swing) that doesn't need to contain source files.
Arguments are separated by colons on all operating systems.
Wild cards aren't allowed. Use -sourcepath to specify where to
find the packages. This option doesn't process source files
that are in the source tree but don't belong to the packages.
For example, the following commands generates documentation for
packages named java and javax.swing and all of their
subpackages.
o Linux and macOS:
javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
o Windows:
javadoc -d docs -sourcepath \user\src -subpackages java:javax.swing
-verbose
Provides more detailed messages while the javadoc tool runs.
Without the -verbose option, messages appear for loading the
source files, generating the documentation (one message per
source file), and sorting. The -verbose option causes the
printing of additional messages that specify the number of
milliseconds to parse each Java source file.
--version
Prints version information.
-Werror
Reports an error if any warnings occur.
Note that if a Java source file contains an implicitly declared class,
then that class and its public, protected, and package members will be
documented regardless of the options such as --show-types,
--show-members, -private, -protected, -package, and -public. If
--show-members is specified with value private or if -private is used
then all private members of an implicitly declared class will be
documented too.
Extra javadoc Options
Note: The additional options for javadoc are subject to change without
notice.
The following additional javadoc options are equivalent to
corresponding javac options. See Extra Options in javac for the
detailed descriptions of using these options:
o --add-exports
o --add-reads
o --patch-module
o -Xmaxerrs
o -Xmaxwarns
Standard Options for the Standard Doclet
The following options are provided by the standard doclet.
--add-script file
Adds file as an additional JavaScript file to the generated
documentation. This option can be used one or more times to
specify additional script files.
Command-line example:
javadoc --add-script first_script.js --add-script
second_script.js pkg_foo
--add-stylesheet file
Adds file as an additional stylesheet file to the generated
documentation. This option can be used one or more times to
specify additional stylesheets included in the documentation.
Command-line example:
javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo
--allow-script-in-comments
Allow JavaScript in options and comments.
-author
Includes the @author text in the generated docs.
-bottom html-code
Specifies the text to be placed at the bottom of each output
file. The text is placed at the bottom of the page, underneath
the lower navigation bar. The text can contain HTML tags and
white space, but when it does, the text must be enclosed in
quotation marks. Use escape characters for any internal
quotation marks within text.
-charset name
Specifies the HTML character set for this document. The name
should be a preferred MIME name as specified in the IANA
Registry, Character Sets
[http://www.iana.org/assignments/character-sets].
For example:
javadoc -charset "iso-8859-1" mypackage
This command inserts the following line in the head of every
generated page:
The meta tag is described in the HTML standard (4197265 and
4137321), HTML Document Representation
[http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2].
-d directory
Specifies the destination directory where the javadoc tool saves
the generated HTML files. If you omit the -d option, then the
files are saved to the current directory. The directory value
can be absolute or relative to the current working directory.
The destination directory is automatically created when the
javadoc tool runs.
o Linux and macOS: For example, the following command generates
the documentation for the package com.mypackage and saves the
results in the /user/doc/ directory:
javadoc -d /user/doc/ com.mypackage
o Windows: For example, the following command generates the
documentation for the package com.mypackage and saves the
results in the \user\doc\ directory:
javadoc -d \user\doc\ com.mypackage
-docencoding name
Specifies the encoding of the generated HTML files. The name
should be a preferred MIME name as specified in the IANA
Registry, Character Sets
[http://www.iana.org/assignments/character-sets].
Three options are available for use in a javadoc encoding
command. The -encoding option is used for encoding the files
read by the javadoc tool, while the -docencoding and -charset
options are used for encoding the files written by the tool. Of
the three available options, at most, only the input and an
output encoding option are used in a single encoding command.
If you specify both input and output encoding options in a
command, they must be the same value. If you specify neither
output option, it defaults to the input encoding.
For example:
javadoc -docencoding "iso-8859-1" mypackage
-docfilessubdirs
Recursively copies doc-file subdirectories. Enables deep
copying of doc-files directories. Subdirectories and all
contents are recursively copied to the destination. For
example, the directory doc-files/example/images and all of its
contents are copied. The -excludedocfilessubdir option can be
used to exclude specific subdirectories.
-doctitle html-code
Specifies the title to place near the top of the overview
summary file. The text specified in the title tag is placed as
a centered, level-one heading directly beneath the top
navigation bar. The title tag can contain HTML tags and white
space, but when it does, you must enclose the title in quotation
marks. Additional quotation marks within the title tag must be
escaped. For example, javadoc -doctitle "My
Library
v1.0" com.mypackage.
-excludedocfilessubdir name1,name2...
Excludes any subdirectories with the given names when
recursively copying doc-file subdirectories. See
-docfilessubdirs. For historical reasons, : can be used
anywhere in the argument as a separator instead of ,.
-footer html-code
Specifies the footer text to be placed at the bottom of each
output file. Thehtml-code value is placed to the right of the
lower navigation bar. The html-code value can contain HTML tags
and white space, but when it does, the html-code value must be
enclosed in quotation marks. Use escape characters for any
internal quotation marks within a footer.
-group name p1,p2...
Group the specified packages together in the Overview page. For
historical reasons, : can be used as a separator anywhere in the
argument instead of ,.
-header html-code
Specifies the header text to be placed at the top of each output
file. The header is placed to the right of the upper navigation
bar. The header can contain HTML tags and white space, but when
it does, the header must be enclosed in quotation marks. Use
escape characters for internal quotation marks within a header.
For example, javadoc -header "My Library
v1.0"
com.mypackage.
-helpfile filename
Includes the file that links to the HELP link in the top and
bottom navigation bars . Without this option, the javadoc tool
creates a help file help-doc.html that is hard-coded in the
javadoc tool. This option lets you override the default. The
filename can be any name and isn't restricted to help-doc.html.
The javadoc tool adjusts the links in the navigation bar
accordingly. For example:
o Linux and macOS:
javadoc -helpfile /home/user/myhelp.html java.awt
o Windows:
javadoc -helpfile C:\user\myhelp.html java.awt
-html5 This option is a no-op and is just retained for backwards
compatibility.
--javafx or -javafx
Enables JavaFX functionality. This option is enabled by default
if the JavaFX library classes are detected on the module path.
-keywords
Adds HTML keyword tags to the generated file for each
class. These tags can help search engines that look for
tags find the pages. Most search engines that search the entire
Internet don't look at tags, because pages can misuse
them. Search engines offered by companies that confine their
searches to their own website can benefit by looking at
tags. The tags include the fully qualified name of the
class and the unqualified names of the fields and methods.
Constructors aren't included because they are identical to the
class name. For example, the class String starts with these
keywords:
-link url
Creates links to existing javadoc generated documentation of
externally referenced classes. The url argument is the absolute
or relative URL of the directory that contains the external
javadoc generated documentation. You can specify multiple -link
options in a specified javadoc tool run to link to multiple
documents.
Either a package-list or an element-list file must be in this
url directory (otherwise, use the -linkoffline option).
Note: The package-list and element-list files are generated by
the javadoc tool when generating the API documentation and
should not be modified by the user.
When you use the javadoc tool to document packages, it uses the
package-list file to determine the packages declared in an API.
When you generate API documents for modules, the javadoc tool
uses the element-list file to determine the modules and packages
declared in an API.
The javadoc tool reads the names from the appropriate list file
and then links to the packages or modules at that URL.
When the javadoc tool runs, the url value is copied into the links that are created. Therefore, url must be the URL to
the directory and not to a file.
You can use an absolute link for url to enable your documents to
link to a document on any web site, or you can use a relative
link to link only to a relative location. If you use a relative
link, then the value you pass in should be the relative path
from the destination directory (specified with the -d option) to
the directory containing the packages being linked to. When you
specify an absolute link, you usually use an HTTP link.
However, if you want to link to a file system that has no web
server, then you can use a file link. Use a file link only when
everyone who wants to access the generated documentation shares
the same file system. In all cases, and on all operating
systems, use a slash as the separator, whether the URL is
absolute or relative, and https:, http:, or file: as specified
in the URL Memo: Uniform Resource Locators
[http://www.ietf.org/rfc/rfc1738.txt].
-link https:// 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, syntax, reference.
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 22-ea 2024 JAVADOC(1)