.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.

.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

.\"

.\" This code is free software; you can redistribute it and/or modify it

.\" under the terms of the GNU General Public License version 2 only, as

.\" published by the Free Software Foundation.

.\"

.\" This code is distributed in the hope that it will be useful, but WITHOUT

.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

.\" version 2 for more details (a copy is included in the LICENSE file that

.\" accompanied this code).

.\"

.\" You should have received a copy of the GNU General Public License version

.\" 2 along with this work; if not, write to the Free Software Foundation,

.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

.\"

.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

.\" or visit www.oracle.com if you need additional information or have any

.\" questions.

.\"

.\" Automatically generated by Pandoc 2.3.1

.\"

.TH "JAVADOC" "1" "2018" "JDK 13" "JDK Commands"

.hy

.SH NAME

.PP

javadoc \- generate HTML pages of API documentation from Java source

files

.SH SYNOPSIS

.PP

\f[CB]javadoc\f[R] [\f[I]options\f[R]] [\f[I]packagenames\f[R]]

[\f[I]sourcefiles\f[R]] [\f[CB]\@\f[R]\f[I]files\f[R]]

.TP

.B \f[I]options\f[R]

Specifies command\-line options, separated by spaces.

See \f[B]Options for javadoc\f[R], \f[B]Extended Options\f[R],

\f[B]Standard doclet Options\f[R], and \f[B]Additional Options Provided

by the Standard doclet\f[R].

.RS

.RE

.TP

.B \f[I]packagenames\f[R]

Specifies names of packages that you want to document, separated by

spaces, for example \f[CB]java.lang\ java.lang.reflect\ java.awt\f[R].

If you want to also document the subpackages, then use the

\f[CB]\-subpackages\f[R] option to specify the packages.

.RS

.PP

By default, \f[CB]javadoc\f[R] looks for the specified packages in the

current directory and subdirectories.

Use the \f[CB]\-sourcepath\f[R] option to specify the list of directories

where to look for packages.

.RE

.TP

.B \f[I]sourcefiles\f[R]

Specifies names of Java source files that you want to document,

separated by spaces, for example

\f[CB]Class.java\ Object.java\ Button.java\f[R].

By default, \f[CB]javadoc\f[R] 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

\f[CB]/home/src/java/awt/Graphics*.java\f[R].

You can also specify the path relative to the current directory.

.RS

.RE

.TP

.B \f[CB]\@\f[R]\f[I]files\f[R]

Specifies names of files that contain a list of \f[CB]javadoc\f[R] tool

options, package names, and source file names in any order.

.RS

.RE

.SH DESCRIPTION

.PP

The \f[CB]javadoc\f[R] 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 classes (but not anonymous inner classes), interfaces,

constructors, methods, and fields.

You can use the \f[CB]javadoc\f[R] tool to generate the API documentation

or the implementation documentation for a set of source files.

.PP

You can run the \f[CB]javadoc\f[R] tool on entire packages, individual

source files, or both.

When documenting entire packages, you can use the \f[CB]\-subpackages\f[R]

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.

See \f[B]javadoc Overview\f[R]

[https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase/13/tools&id=JSJAV\-GUID\-7A344353\-3BBF\-45C4\-8B28\-15025DDCC643]

in Java Platform, Standard Edition Javadoc Guide for information about

using the \f[CB]javadoc\f[R] tool.

.SH CONFORMANCE

.PP

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 \f[CB]doclint\f[R] 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.

.PP

For more details on the conformance requirements for HTML5 documents,

see \f[B]Conformance requirements\f[R]

[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

\f[B]Open Web Application Security Project (OWASP)\f[R]

[https://www.owasp.org] page.

.SH OPTIONS FOR JAVADOC

.PP

The following core \f[CB]javadoc\f[R] options are equivalent to

corresponding \f[CB]javac\f[R] options.

See \f[I]Standard Options\f[R] in \f[B]javac\f[R] for the detailed

descriptions of using these options:

.IP \[bu] 2

\f[CB]\-\-add\-modules\f[R]

.IP \[bu] 2

\f[CB]\-bootclasspath\f[R]

.IP \[bu] 2

\f[CB]\-\-class\-path\f[R], \f[CB]\-classpath\f[R], or \f[CB]\-cp\f[R]

.IP \[bu] 2

\f[CB]\-\-enable\-preview\f[R]

.IP \[bu] 2

\f[CB]\-encoding\f[R]

.IP \[bu] 2

\f[CB]\-extdirs\f[R]

.IP \[bu] 2

\f[CB]\-\-limit\-modules\f[R]

.IP \[bu] 2

\f[CB]\-\-module\f[R]

.IP \[bu] 2

\f[CB]\-\-module\-path\f[R] or \f[CB]\-p\f[R]

.IP \[bu] 2

\f[CB]\-\-module\-source\-path\f[R]

.IP \[bu] 2

\f[CB]\-\-release\f[R]

.IP \[bu] 2

\f[CB]\-source\f[R]

.IP \[bu] 2

\f[CB]\-\-source\-path\f[R] or \f[CB]\-sourcepath\f[R]

.IP \[bu] 2

\f[CB]\-\-system\f[R]

.IP \[bu] 2

\f[CB]\-\-upgrade\-module\-path\f[R]

.PP

The following options are the core \f[CB]javadoc\f[R] options that are not

equivalent to a corresponding \f[CB]javac\f[R] option:

.PP

\f[B]Note:\f[R]

.PP

In tools that support \f[CB]\-\-\f[R] style options, the GNU\-style

options can use the equal sign (=) instead of a white space to separate

the name of an option from its value.

.TP

.B \f[CB]\-breakiterator\f[R]

Computes the first sentence with \f[CB]BreakIterator\f[R].

The first sentence is copied to the package, class, or member summary

and to the alphabetic index.

The \f[CB]BreakIterator\f[R] class is used to determine the end of a

sentence for all languages except for English.

.RS

.IP \[bu] 2

English default sentence\-break algorithm \-\-\- Stops at a period

followed by a space or an HTML block tag, such as \f[CB]<P>\f[R].

.IP \[bu] 2

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 \f[CB]\-breakiterator\f[R] option doesn\[aq]t stop at HTML tags or

sentences that begin with numbers or symbols.

The algorithm stops at the last period in \f[CB]\&../filename\f[R], even

when embedded in an HTML tag.

.RE

.TP

.B \f[CB]\-doclet\f[R] \f[I]class\f[R]

Generates output by using an alternate doclet.

Use the fully qualified name.

This doclet defines the content and formats the output.

If the \f[CB]\-doclet\f[R] option isn\[aq]t used, then the

\f[CB]javadoc\f[R] tool uses the standard doclet for generating the

default HTML format.

This class must contain the \f[CB]start(Root)\f[R] method.

The path to this starting class is defined by the \f[CB]\-docletpath\f[R]

option.

.RS

.RE

.TP

.B \f[CB]\-docletpath\f[R] \f[I]path\f[R]

Specifies where to find doclet class files (specified with the

\f[CB]\-doclet\f[R] 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 \f[CB]classpathlist\f[R] contains multiple paths or JAR files, then

they should be separated with a colon (\f[CB]:\f[R]) on Oracle Solaris and

a semi\-colon (\f[CB];\f[R]) on Windows.

This option isn\[aq]t necessary when the \f[CB]doclet\f[R] starting class

is already in the search path.

.RS

.RE

.TP

.B \f[CB]\-exclude\f[R] \f[I]pkglist\f[R]

Unconditionally, excludes the specified packages and their subpackages

from the list formed by \f[CB]\-subpackages\f[R].

It excludes those packages even when they would otherwise be included by

some earlier or later \f[CB]\-subpackages\f[R] option.

.RS

.PP

The following example would include \f[CB]java.io\f[R],

\f[CB]java.util\f[R], and \f[CB]java.math\f[R] (among others), but would

exclude packages rooted at \f[CB]java.net\f[R] and \f[CB]java.lang\f[R].

Notice that these examples exclude \f[CB]java.lang.ref\f[R], which is a

subpackage of \f[CB]java.lang\f[R].

.IP \[bu] 2

\f[B]Oracle Solaris, Linux, and OS X:\f[R]

.RS 2

.RS

.PP

\f[CB]javadoc\ \-sourcepath\ /home/user/src\ \-subpackages\ java\ \-exclude\ java.net:java.lang\f[R]

.RE

.RE

.IP \[bu] 2

\f[B]Windows:\f[R]

.RS 2

.RS

.PP

\f[CB]javadoc\ \-sourcepath\ \\user\\src\ \-subpackages\ java\ \-exclude\ java.net:java.lang\f[R]

.RE

.RE

.RE

.TP

.B \f[CB]\-\-expand\-requires\f[R] \f[I]value\f[R]

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:

.RS

.IP \[bu] 2

\f[CB]transitive\f[R]: additionally includes all the required transitive

dependencies of those modules.

.IP \[bu] 2

\f[CB]all\f[R]: includes all dependencies.

.RE

.TP

.B \f[CB]\-help\f[R] or \f[CB]\-\-help\f[R]

Displays the online help, which lists all of the \f[CB]javadoc\f[R] and

\f[CB]doclet\f[R] command\-line options.

.RS

.RE

.TP

.B \f[CB]\-\-help\-extra\f[R] or \f[CB]\-X\f[R]

Prints a synopsis of non\-standard options and exits.

.RS

.RE

.TP

.B \f[CB]\-J\f[R]\f[I]flag\f[R]

Passes \f[I]flag\f[R] directly to the Java Runtime Environment (JRE) that

runs the \f[CB]javadoc\f[R] 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 \f[CB]\-Xmx\f[R] option as follows:

\f[CB]javadoc\ \-J\-Xmx32m\ \-J\-Xms32m\ com.mypackage\f[R].

Be aware that \f[CB]\-Xms\f[R] is optional because it only sets the size

of initial memory, which is useful when you know the minimum amount of

memory required.

.RS

.PP

There is no space between the \f[CB]J\f[R] and the \f[CB]flag\f[R].

.PP

Use the \f[CB]\-version\f[R] option to report the version of the JRE being

used to run the \f[CB]javadoc\f[R] tool.

.IP

.nf

\f[CB]

javadoc\ \-J\-version

java\ version\ "10\-ea"\ 2018\-03\-20

Java(TM)\ SE\ Runtime\ Environment\ 18.3\ (build\ 10\-ea+36)

Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ 18.3\ (build\ 10\-ea+36,\ mixed\ mode)

\f[R]

.fi

.RE

.TP

.B \f[CB]\-locale\f[R] \f[I]name\f[R]

Specifies the locale that the \f[CB]javadoc\f[R] tool uses when it

generates documentation.

The argument is the name of the locale, as described in

\f[CB]java.util.Locale\f[R] documentation, such as \f[CB]en_US\f[R]

(English, United States) or \f[CB]en_US_WIN\f[R] (Windows variant).

.RS

.PP

\f[B]Note:\f[R]

.PP

The \f[CB]\-locale\f[R] option must be placed ahead (to the left) of any

options provided by the standard doclet or any other doclet.

Otherwise, the navigation bars appear in English.

This is the only command\-line option that depends on order.

.PP

Specifying a locale causes the \f[CB]javadoc\f[R] 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 \f[CB]stylesheet.css\f[R] 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 \f[CB]\-locale\f[R] option doesn\[aq]t determine the locale of the

documentation comment text specified in the source files of the

documented classes.

.RE

.TP

.B \f[CB]\-package\f[R]

Shows only package, protected, and public classes and members.

.RS

.RE

.TP

.B \f[CB]\-private\f[R]

Shows all classes and members.

.RS

.RE

.TP

.B \f[CB]\-protected\f[R]

Shows only protected and public classes and members.

This is the default.

.RS

.RE

.TP

.B \f[CB]\-public\f[R]

Shows only the public classes and members.

.RS

.RE

.TP

.B \f[CB]\-quiet\f[R]

Shuts off messages so that only the warnings and errors appear to make

them easier to view.

It also suppresses the \f[CB]version\f[R] string.

.RS

.RE

.TP

.B \f[CB]\-\-show\-members\f[R] \f[I]value\f[R]

Specifies which members (fields or methods) are documented, where

\f[I]value\f[R] can be any of the following:

.RS

.IP \[bu] 2

\f[CB]protected\f[R]: The default value is protected.

.IP \[bu] 2

\f[CB]public\f[R]: Shows only public values.

.IP \[bu] 2

\f[CB]package\f[R]: Shows public, protected, and package members.

.IP \[bu] 2

\f[CB]private\f[R]: Shows all members.

.RE

.TP

.B \f[CB]\-\-show\-module\-contents\f[R] \f[I]value\f[R]

Specifies the documentation granularity of module declarations, where

\f[I]value\f[R] can be \f[CB]api\f[R] or \f[CB]all\f[R].

.RS

.RE

.TP

.B \f[CB]\-\-show\-packages\f[R] \f[I]value\f[R]

Specifies which modules packages are documented, where \f[I]value\f[R]

can be \f[CB]exported\f[R] or \f[CB]all\f[R] packages.

.RS

.RE

.TP

.B \f[CB]\-\-show\-types\f[R] \f[I]value\f[R]

Specifies which types (classes, interfaces, etc.) are documented, where

\f[I]value\f[R] can be any of the following:

.RS

.IP \[bu] 2

\f[CB]protected\f[R]: The default value.

Shows public and protected types.

.IP \[bu] 2

\f[CB]public\f[R]: Shows only public values.

.IP \[bu] 2

\f[CB]package\f[R]: Shows public, protected, and package types.

.IP \[bu] 2

\f[CB]private\f[R]: Shows all types.

.RE

.TP

.B \f[CB]\-subpackages\f[R] \f[I]subpkglist\f[R]

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

\f[CB]java\f[R]) or fully qualified package (such as \f[CB]javax.swing\f[R])

that doesn\[aq]t need to contain source files.

Arguments are separated by colons on all operating systems.

Wild cards aren\[aq]t allowed.

Use \f[CB]\-sourcepath\f[R] to specify where to find the packages.

This option doesn\[aq]t process source files that are in the source tree

but don\[aq]t belong to the packages.

.RS

.PP

For example, the following commands generates documentation for packages

named \f[CB]java\f[R] and \f[CB]javax.swing\f[R] and all of their

subpackages.

.IP \[bu] 2

\f[B]Oracle Solaris, Linux, and OS X:\f[R]

.RS 2

.RS

.PP

\f[CB]javadoc\ \-d\ docs\ \-sourcepath\ /home/user/src\ \-subpackages\ java:javax.swing\f[R]

.RE

.RE

.IP \[bu] 2

\f[B]Windows:\f[R]

.RS 2

.RS

.PP

\f[CB]javadoc\ \-d\ docs\ \-sourcepath\ \\user\\src\ \-subpackages\ java:javax.swing\f[R]

.RE

.RE

.RE

.TP

.B \f[CB]\-verbose\f[R]

Provides more detailed messages while the \f[CB]javadoc\f[R] tool runs.

Without the \f[CB]\-verbose\f[R] option, messages appear for loading the

source files, generating the documentation (one message per source

file), and sorting.

The \f[CB]\-verbose\f[R] option causes the printing of additional messages

that specify the number of milliseconds to parse each Java source file.

.RS

.RE

.TP

.B \f[CB]\-\-version\f[R]

Prints version information.

.RS

.RE

.SH EXTENDED OPTIONS

.PP

\f[B]Note:\f[R]

.PP

The extended options for \f[CB]javadoc\f[R] are subject to change without

notice.

.PP

The following extended \f[CB]javadoc\f[R] options are equivalent to

corresponding \f[CB]javac\f[R] options.

See \f[I]Extra Options\f[R] in \f[B]javac\f[R] for the detailed

descriptions of using these options:

.IP \[bu] 2

\f[CB]\-\-add\-exports\f[R]

.IP \[bu] 2

\f[CB]\-\-add\-reads\f[R]

.IP \[bu] 2

\f[CB]\-\-patch\-module\f[R]

.IP \[bu] 2

\f[CB]\-Xmaxerrs\f[R]

.IP \[bu] 2

\f[CB]\-Xmaxwarns\f[R]

.PP

The following extended \f[CB]javadoc\f[R] options are not equivalent to a

corresponding \f[CB]javac\f[R] option:

.TP

.B \f[CB]\-Xmodule:\f[R]\f[I]module\-name\f[R]

Specifies a module to which the classes being compiled belong.

.RS

.RE

.TP

.B \f[CB]\-Xold\f[R]

Invokes the legacy javadoc tool.

.RS

.RE

.SH STANDARD DOCLET OPTIONS

.PP

The following options are provided by the standard doclet.

.TP

.B \f[CB]\-\-add\-stylesheet\f[R] \f[I]file\f[R]

Adds additional stylesheet file for the generated documentation.

This option can be used one or more times to specify additional

stylesheets included in the documentation.

.RS

.PP

Command\-line example:

.RS

.PP

\f[CB]javadoc\ \-\-add\-stylesheet\ new_stylesheet_1.css\ \-\-add\-stylesheet\ new_stylesheet_2.css\ pkg_foo\f[R]

.RE

.RE

.TP

.B \f[CB]\-\-allow\-script\-in\-comments\f[R]

Allow JavaScript in options and comments

.RS

.RE