1302 lines
46 KiB
Groff
1302 lines
46 KiB
Groff
.\" 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/11/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
|
|
.TP
|
|
.B \f[CB]\-author\f[R]
|
|
Includes the \f[CB]\@author\f[R] text in the generated docs.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-bottom\f[R] \f[I]html\-code\f[R]
|
|
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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-charset\f[R] \f[I]name\f[R]
|
|
Specifies the HTML character set for this document.
|
|
The name should be a preferred MIME name as specified in the \f[B]IANA
|
|
Registry, Character Sets\f[R]
|
|
[http://www.iana.org/assignments/character\-sets].
|
|
.RS
|
|
.PP
|
|
For example:
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-charset\ "iso\-8859\-1"\ mypackage\f[R]
|
|
.RE
|
|
.PP
|
|
This command inserts the following line in the head of every generated
|
|
page:
|
|
.RS
|
|
.PP
|
|
\f[CB]<META\ http\-equiv="Content\-Type"\ content="text/html;\ charset=ISO\-8859\-1">\f[R]
|
|
.RE
|
|
.PP
|
|
The \f[CB]META\f[R] tag is described in the \f[B]HTML standard (4197265
|
|
and 4137321), HTML Document Representation\f[R]
|
|
[http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2].
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-d\f[R] \f[I]directory\f[R]
|
|
Specifies the destination directory where the \f[CB]javadoc\f[R] tool
|
|
saves the generated HTML files.
|
|
If you omit the \f[CB]\-d\f[R] option, then the files are saved to the
|
|
current directory.
|
|
The \f[CB]directory\f[R] value can be absolute or relative to the current
|
|
working directory.
|
|
The destination directory is automatically created when the
|
|
\f[CB]javadoc\f[R] tool runs.
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[B]Oracle Solaris, Linux, and OS X:\f[R] For example, the following
|
|
command generates the documentation for the package
|
|
\f[CB]com.mypackage\f[R] and saves the results in the \f[CB]/user/doc/\f[R]
|
|
directory:
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-d\ /user/doc/\ com.mypackage\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[B]Windows:\f[R] For example, the following command generates the
|
|
documentation for the package \f[CB]com.mypackage\f[R] and saves the
|
|
results in the \f[CB]\\user\\doc\\\f[R] directory:
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-d\ \\user\\doc\\\ com.mypackage\f[R]
|
|
.RE
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-docencoding\f[R] \f[I]name\f[R]
|
|
Specifies the encoding of the generated HTML files.
|
|
The name should be a preferred MIME name as specified in the \f[B]IANA
|
|
Registry, Character Sets\f[R]
|
|
[http://www.iana.org/assignments/character\-sets].
|
|
.RS
|
|
.PP
|
|
Three options are available for use in a \f[CB]javadoc\f[R] encoding
|
|
command.
|
|
The \f[CB]\-encoding\f[R] option is used for encoding the files read by
|
|
the \f[CB]javadoc\f[R] tool, while the \f[CB]\-docencoding\f[R] and
|
|
\f[CB]\-charset\f[R] 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 the tool defaults to the input
|
|
encoding.
|
|
.PP
|
|
For example:
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-docencoding\ "iso\-8859\-1"\ mypackage\f[R]
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-docfilessubdirs\f[R]
|
|
Recursively copies doc\-file subdirectories.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-doctitle\f[R] \f[I]html\-code\f[R]
|
|
Specifies the title to place near the top of the overview summary file.
|
|
The text specified in the \f[CB]title\f[R] tag is placed as a centered,
|
|
level\-one heading directly beneath the top navigation bar.
|
|
The \f[CB]title\f[R] 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 \f[CB]title\f[R] tag must be
|
|
escaped.
|
|
For example,
|
|
\f[CB]javadoc\ \-header\ "<b>My\ Library</b><br>v1.0"\ com.mypackage.\f[R]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-excludedocfilessubdir\f[R] \f[I]name\f[R]
|
|
Excludes any doc files sub directories with the given name.
|
|
Enables deep copying of doc\-files directories.
|
|
Subdirectories and all contents are recursively copied to the
|
|
destination.
|
|
For example, the directory \f[CB]doc\-files/example/images\f[R] and all of
|
|
its contents are copied.
|
|
There is also an option to exclude subdirectories.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-footer\f[R] \f[I]html\-code\f[R]
|
|
Specifies the footer text to be placed at the bottom of each output
|
|
file.
|
|
The\f[CB]html\-code\f[R] value is placed to the right of the lower
|
|
navigation bar.
|
|
The \f[CB]html\-code\f[R] value can contain HTML tags and white space, but
|
|
when it does, the \f[CB]html\-code\f[R] value must be enclosed in
|
|
quotation marks.
|
|
Use escape characters for any internal quotation marks within a footer.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-frames\f[R]
|
|
Enables the use of frames in the generated output (default).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-group\f[R] \f[I]namep1\f[R]\f[CB]:\f[R]\f[I]p2\f[R]
|
|
Group the specified packages together in the Overview page.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-header\f[R] \f[I]html\-code\f[R]
|
|
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 \f[CB]header\f[R] can contain HTML tags and white space, but when it
|
|
does, the \f[CB]header\f[R] must be enclosed in quotation marks.
|
|
Use escape characters for internal quotation marks within a header.
|
|
For example,
|
|
\f[CB]javadoc\ \-header\ "<b>My\ Library</b><br>v1.0"\ com.mypackage.\f[R]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-helpfile\f[R] \f[I]filename\f[R]
|
|
Includes the file that links to the \f[B]HELP\f[R] link in the top and
|
|
bottom navigation bars .
|
|
Without this option, the \f[CB]javadoc\f[R] tool creates a help file
|
|
\f[CB]help\-doc.html\f[R] that is hard\-coded in the \f[CB]javadoc\f[R]
|
|
tool.
|
|
This option lets you override the default.
|
|
The \f[I]filename\f[R] can be any name and isn\[aq]t restricted to
|
|
\f[CB]help\-doc.html\f[R].
|
|
The \f[CB]javadoc\f[R] tool adjusts the links in the navigation bar
|
|
accordingly.
|
|
For example:
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[B]Oracle Solaris, Linux, and OS X:\f[R]
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-helpfile\ /home/user/myhelp.html\ java.awt.\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[B]Windows:\f[R]
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-helpfile\ C:\\user\\myhelp.html\ java.awt.\f[R]
|
|
.RE
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-html4\f[R]
|
|
Generates HTML 4.0.1 output.
|
|
If the option is not used, \f[CB]\-html4\f[R] is the default
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-html5\f[R]
|
|
Generates HTML 5 output.
|
|
If the option is not used, \f[CB]\-html4\f[R] is the default.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-javafx\f[R] or \f[CB]\-javafx\f[R]
|
|
Enables JavaFX functionality.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-keywords\f[R]
|
|
Adds HTML keyword \f[CB]<META>\f[R] tags to the generated file for each
|
|
class.
|
|
These tags can help search engines that look for \f[CB]<META>\f[R] tags
|
|
find the pages.
|
|
Most search engines that search the entire Internet don\[aq]t look at
|
|
\f[CB]<META>\f[R] tags, because pages can misuse them.
|
|
Search engines offered by companies that confine their searches to their
|
|
own website can benefit by looking at \f[CB]<META>\f[R] tags.
|
|
The \f[CB]<META>\f[R] tags include the fully qualified name of the class
|
|
and the unqualified names of the fields and methods.
|
|
Constructors aren\[aq]t included because they are identical to the class
|
|
name.
|
|
For example, the class \f[CB]String\f[R] starts with these keywords:
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
<META\ NAME="keywords"\ CONTENT="java.lang.String\ class">
|
|
<META\ NAME="keywords"\ CONTENT="CASE_INSENSITIVE_ORDER">
|
|
<META\ NAME="keywords"\ CONTENT="length()">
|
|
<META\ NAME="keywords"\ CONTENT="charAt()">
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-link\f[R] \f[I]url\f[R]
|
|
Creates links to existing \f[CB]javadoc\f[R] generated documentation of
|
|
externally referenced classes.
|
|
The \f[I]url\f[R] argument is the absolute or relative URL of the
|
|
directory that contains the external \f[CB]javadoc\f[R] generated
|
|
documentation.
|
|
You can specify multiple \f[CB]\-link\f[R] options in a specified
|
|
\f[CB]javadoc\f[R] tool run to link to multiple documents.
|
|
.RS
|
|
.PP
|
|
Either a \f[CB]package\-list\f[R] or an \f[CB]element\-list\f[R] file must
|
|
be in this \f[I]url\f[R] directory (otherwise, use the
|
|
\f[CB]\-linkoffline\f[R] option).
|
|
.PP
|
|
\f[B]Note:\f[R]
|
|
.PP
|
|
The \f[CB]package\-list\f[R] and \f[CB]element\-list\f[R] files are
|
|
generated by the \f[CB]javadoc\f[R] tool when generating the API
|
|
documentation and should not be modified by the user.
|
|
.PP
|
|
When you use the \f[CB]javadoc\f[R] tool to document packages, it uses the
|
|
\f[CB]package\-list\f[R] file to determine the packages declared in an
|
|
API.
|
|
When you generate API documents for modules, the \f[CB]javadoc\f[R] tool
|
|
uses the \f[CB]element\-list\f[R] file to determine the modules and
|
|
packages declared in an API.
|
|
.PP
|
|
The \f[CB]javadoc\f[R] tool reads the names from the appropriate list file
|
|
and then links to the packages or modules at that URL.
|
|
.PP
|
|
When the \f[CB]javadoc\f[R] tool runs, the \f[I]url\f[R] value is copied
|
|
into the \f[CB]<A\ HREF>\f[R] links that are created.
|
|
Therefore, \f[I]url\f[R] must be the URL to the directory and not to a
|
|
file.
|
|
.PP
|
|
You can use an absolute link for \f[I]url\f[R] 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
|
|
\f[CB]\-d\f[R] 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 \f[CB]https:\f[R],
|
|
\f[CB]http:\f[R], or \f[CB]file:\f[R] as specified in the \f[B]URL Memo:
|
|
Uniform Resource Locators\f[R] [http://www.ietf.org/rfc/rfc1738.txt].
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
\-link\ https://<host>/<directory>/<directory>/.../<name>
|
|
\-link\ http://<host>/<directory>/<directory>/.../<name>
|
|
\-link\ file://<host>/<directory>/<directory>/.../<name>
|
|
\-link\ <directory>/<directory>/.../<name>
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-linkoffline\f[R] \f[I]url1\f[R] \f[I]url2\f[R]
|
|
This option is a variation of the \f[CB]\-link\f[R] option.
|
|
They both create links to \f[CB]javadoc\f[R] generated documentation for
|
|
externally referenced classes.
|
|
You can specify multiple \f[CB]\-linkoffline\f[R] options in a specified
|
|
\f[CB]javadoc\f[R] tool run.
|
|
.RS
|
|
.PP
|
|
Use the \f[CB]\-linkoffline\f[R] option when:
|
|
.IP \[bu] 2
|
|
Linking to a document on the web that the \f[CB]javadoc\f[R] tool
|
|
can\[aq]t access through a web connection
|
|
.IP \[bu] 2
|
|
The \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R] file of the
|
|
external document either isn\[aq]t accessible or doesn\[aq]t exist at
|
|
the URL location, but does exist at a different location and can be
|
|
specified by either the \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R]
|
|
file (typically local).
|
|
.PP
|
|
\f[B]Note:\f[R]
|
|
.PP
|
|
The \f[CB]package\-list\f[R] and \f[CB]element\-list\f[R] files are
|
|
generated by the \f[CB]javadoc\f[R] tool when generating the API
|
|
documentation and should not be modified by the user.
|
|
.PP
|
|
If \f[I]url1\f[R] is accessible only on the World Wide Web, then the
|
|
\f[CB]\-linkoffline\f[R] option removes the constraint that the
|
|
\f[CB]javadoc\f[R] tool must have a web connection to generate
|
|
documentation.
|
|
.PP
|
|
Another use of the \f[CB]\-linkoffline\f[R] option is as a work\-around to
|
|
update documents.
|
|
After you have run the \f[CB]javadoc\f[R] tool on a full set of packages
|
|
or modules, you can run the \f[CB]javadoc\f[R] tool again on a smaller set
|
|
of changed packages or modules, so that the updated files can be
|
|
inserted back into the original set.
|
|
.PP
|
|
For example, the \f[CB]\-linkoffline\f[R] option takes two arguments.
|
|
The first is for the string to be embedded in the \f[CB]<a\ href>\f[R]
|
|
links, and the second tells the \f[CB]javadoc\f[R] tool where to find
|
|
either the \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R] file.
|
|
.PP
|
|
The \f[I]url1\f[R] or \f[I]url2\f[R] value is the absolute or relative URL
|
|
of the directory that contains the external \f[CB]javadoc\f[R] generated
|
|
documentation that you want to link to.
|
|
When relative, the value should be the relative path from the
|
|
destination directory (specified with the \f[CB]\-d\f[R] option) to the
|
|
root of the packages being linked to.
|
|
See \f[I]url\f[R] in the \f[CB]\-link\f[R] option.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-linksource\f[R]
|
|
Creates an HTML version of each source file (with line numbers) and adds
|
|
links to them from the standard HTML documentation.
|
|
Links are created for classes, interfaces, constructors, methods, and
|
|
fields whose declarations are in a source file.
|
|
Otherwise, links aren\[aq]t created, such as for default constructors
|
|
and generated classes.
|
|
.RS
|
|
.PP
|
|
This option exposes all private implementation details in the included
|
|
source files, including private classes, private fields, and the bodies
|
|
of private methods, regardless of the \f[CB]\-public\f[R],
|
|
\f[CB]\-package\f[R], \f[CB]\-protected\f[R], and \f[CB]\-private\f[R]
|
|
options.
|
|
Unless you also use the \f[CB]\-private\f[R] option, not all private
|
|
classes or interfaces are accessible through links.
|
|
.PP
|
|
Each link appears on the name of the identifier in its declaration.
|
|
For example, the link to the source code of the \f[CB]Button\f[R] class
|
|
would be on the word \f[CB]Button\f[R]:
|
|
.RS
|
|
.PP
|
|
\f[CB]public\ class\ Button\ extends\ Component\ implements\ Accessible\f[R]
|
|
.RE
|
|
.PP
|
|
The link to the source code of the \f[CB]getLabel\f[R] method in the
|
|
\f[CB]Button\f[R] class is on the word \f[CB]getLabel\f[R]:
|
|
.RS
|
|
.PP
|
|
\f[CB]public\ String\ getLabel()\f[R]
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-main\-stylesheet\f[R] \f[I]file\f[R] or \f[CB]\-stylesheetfile\f[R] \f[I]file\f[R]
|
|
Specifies the path of an alternate stylesheet file that contains the
|
|
definitions for the CSS styles used in the generated documentation.
|
|
This option lets you override the default.
|
|
If you do not specify the option, the \f[CB]javadoc\f[R] tool will create
|
|
and use a default stylesheet.
|
|
The file name can be any name and isn\[aq]t restricted to
|
|
\f[CB]stylesheet.css\f[R].
|
|
The \f[CB]\-\-main\-stylesheet\f[R] option is the preferred form.
|
|
.RS
|
|
.PP
|
|
Command\-line example:
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-\-main\-stylesheet\ main_stylesheet.css\ pkg_foo\f[R]
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nocomment\f[R]
|
|
Suppresses the entire comment body, including the main description and
|
|
all tags, and generate only declarations.
|
|
This option lets you reuse source files that were originally intended
|
|
for a different purpose so that you can produce skeleton HTML
|
|
documentation during the early stages of a new project.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nodeprecated\f[R]
|
|
Prevents the generation of any deprecated API in the documentation.
|
|
This does what the \f[CB]\-nodeprecatedlist\f[R] option does, and it
|
|
doesn\[aq]t generate any deprecated API throughout the rest of the
|
|
documentation.
|
|
This is useful when writing code when you don\[aq]t want to be
|
|
distracted by the deprecated code.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nodeprecatedlist\f[R]
|
|
Prevents the generation of the file that contains the list of deprecated
|
|
APIs (\f[CB]deprecated\-list.html\f[R]) and the link in the navigation bar
|
|
to that page.
|
|
The \f[CB]javadoc\f[R] tool continues to generate the deprecated API
|
|
throughout the rest of the document.
|
|
This is useful when your source code contains no deprecated APIs, and
|
|
you want to make the navigation bar cleaner.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-no\-frames\f[R]
|
|
Disables the use of frames in the generated output.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nohelp\f[R]
|
|
Omits the HELP link in the navigation bars at the top and bottom of each
|
|
page of output.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-noindex\f[R]
|
|
Omits the index from the generated documents.
|
|
The index is produced by default.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nonavbar\f[R]
|
|
Prevents the generation of the navigation bar, header, and footer, that
|
|
are usually found at the top and bottom of the generated pages.
|
|
The \f[CB]\-nonavbar\f[R] option has no affect on the \f[CB]\-bottom\f[R]
|
|
option.
|
|
The \f[CB]\-nonavbar\f[R] option is useful when you are interested only in
|
|
the content and have no need for navigation, such as when you are
|
|
converting the files to PostScript or PDF for printing only.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-noqualifier\f[R] \f[I]name1\f[R]\f[CB]:\f[R]\f[I]name2\f[R]...
|
|
Excludes the list of qualifiers from the output.
|
|
The package name is removed from places where class or interface names
|
|
appear.
|
|
.RS
|
|
.PP
|
|
The following example omits all package qualifiers:
|
|
\f[CB]\-noqualifier\ all\f[R].
|
|
.PP
|
|
The following example omits \f[CB]java.lang\f[R] and \f[CB]java.io\f[R]
|
|
package qualifiers: \f[CB]\-noqualifier\ java.lang:java.io\f[R].
|
|
.PP
|
|
The following example omits package qualifiers starting with
|
|
\f[CB]java\f[R] and \f[CB]com.sun\f[R] subpackages, but not
|
|
\f[CB]javax:\ \-noqualifier\ java.*:com.sun.*\f[R].
|
|
.PP
|
|
Where a package qualifier would appear due to the previous behavior, the
|
|
name can be suitably shortened.
|
|
This rule is in effect whether or not the \f[CB]\-noqualifier\f[R] option
|
|
is used.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-nosince\f[R]
|
|
Omits from the generated documents the \f[CB]Since\f[R] sections
|
|
associated with the \f[CB]\@since\f[R] tags.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-notimestamp\f[R]
|
|
Suppresses the time stamp, which is hidden in an HTML comment in the
|
|
generated HTML near the top of each page.
|
|
The \f[CB]\-notimestamp\f[R] option is useful when you want to run the
|
|
\f[CB]javadoc\f[R] tool on two source bases and get the differences
|
|
between \f[CB]diff\f[R] them, because it prevents time stamps from causing
|
|
a \f[CB]diff\f[R] (which would otherwise be a \f[CB]diff\f[R] on every
|
|
page).
|
|
The time stamp includes the \f[CB]javadoc\f[R] tool release number.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-notree\f[R]
|
|
Omits the class and interface hierarchy pages from the generated
|
|
documents.
|
|
These are the pages you reach using the Tree button in the navigation
|
|
bar.
|
|
The hierarchy is produced by default.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-override\-methods\f[R] (\f[CB]detail\f[R]|\f[CB]summary\f[R])
|
|
Documents overridden methods in the detail or summary sections.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-overview\f[R] \f[I]filename\f[R]
|
|
Specifies that the \f[CB]javadoc\f[R] tool should retrieve the text for
|
|
the overview documentation from the source file specified by
|
|
\f[CB]filename\f[R] and place it on the Overview page
|
|
(\f[CB]overview\-summary.html\f[R]).
|
|
A relative path specified with the file name is relative to the current
|
|
working directory.
|
|
.RS
|
|
.PP
|
|
While you can use any name you want for the \f[CB]filename\f[R] value and
|
|
place it anywhere you want for the path, it is typical to name it
|
|
\f[CB]overview.html\f[R] and place it in the source tree at the directory
|
|
that contains the topmost package directories.
|
|
In this location, no path is needed when documenting packages, because
|
|
the \f[CB]\-sourcepath\f[R] option points to this file.
|
|
.IP \[bu] 2
|
|
\f[B]Oracle Solaris, Linux, and OS X:\f[R] For example, if the source
|
|
tree for the \f[CB]java.lang\f[R] package is
|
|
\f[CB]/src/classes/java/lang/\f[R], then you could place the overview file
|
|
at /src/classes/overview.html.
|
|
.IP \[bu] 2
|
|
\f[B]Windows:\f[R] For example, if the source tree for the
|
|
\f[CB]java.lang\f[R] package is \f[CB]\\src\\classes\\java\\lang\\\f[R],
|
|
then you could place the overview file at
|
|
\f[CB]\\src\\classes\\overview.html\f[R]
|
|
.PP
|
|
The overview page is created only when you pass two or more package
|
|
names to the \f[CB]javadoc\f[R] tool.
|
|
The title on the overview page is set by \f[CB]\-doctitle\f[R].
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-serialwarn\f[R]
|
|
Generates compile\-time warnings for missing \f[CB]\@serial\f[R] tags.
|
|
By default, Javadoc generates no serial warnings.
|
|
Use this option to display the serial warnings, which helps to properly
|
|
document default serializable fields and \f[CB]writeExternal\f[R] methods.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-sourcetab\f[R] \f[I]tablength\f[R]
|
|
Specifies the number of spaces each tab uses in the source.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
|
|
Specifies single argument custom tags.
|
|
For the \f[CB]javadoc\f[R] tool to spell\-check tag names, it is important
|
|
to include a \f[CB]\-tag\f[R] option for every custom tag that is present
|
|
in the source code, disabling (with \f[CB]X\f[R]) those that aren\[aq]t
|
|
being output in the current run.
|
|
The colon (\f[CB]:\f[R]) is always the separator.
|
|
The \f[CB]\-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[CB]\@return\f[R] and \f[CB]\@author\f[R] tags.
|
|
Omitting a \f[I]header\f[R] value causes the \f[I]name\f[R] to be the
|
|
heading.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-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[CB]\-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
|
|
.nf
|
|
\f[CB]
|
|
\-taglet\ com.sun.tools.doclets.ToDoTaglet
|
|
\-tagletpath\ /home/taglets
|
|
\-tag\ return
|
|
\-tag\ param
|
|
\-tag\ todo
|
|
\-tag\ throws
|
|
\-tag\ see
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Alternately, you can use the \f[CB]\-taglet\f[R] option in place of its
|
|
\f[CB]\-tag\f[R] option, but that might be difficult to read.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-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 a colon (\f[CB]:\f[R]).
|
|
The \f[CB]javadoc\f[R] tool searches all subdirectories of the specified
|
|
paths.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-top\f[R] \f[I]html\-code\f[R]
|
|
Specifies the text to be placed at the top of each output file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-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[CB]String\f[R] type.
|
|
Because the \f[CB]getName\f[R] method in the \f[CB]java.awt.Font\f[R] class
|
|
returns type \f[CB]String\f[R], the \f[CB]getName\f[R] method uses
|
|
\f[CB]String\f[R] and so the \f[CB]getName\f[R] method appears on the Use
|
|
page for \f[CB]String\f[R].
|
|
This documents only uses of the API, not the implementation.
|
|
When a method uses \f[CB]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[CB]String\f[R].To access the generated
|
|
Use page, go to the class or package and click the \f[B]Use link\f[R] in
|
|
the navigation bar.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-version\f[R]
|
|
Includes the version text in the generated docs.
|
|
This text is omitted by default.
|
|
To find out what version of the \f[CB]javadoc\f[R] tool you are using, use
|
|
the \f[CB]\-J\-version\f[R] option.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-windowtitle\f[R] \f[I]title\f[R]
|
|
Specifies the title to be placed in the HTML \f[CB]<title>\f[R] tag.
|
|
The text specified in the \f[CB]title\f[R] tag appears in the window title
|
|
and in any browser bookmarks (favorite places) that someone creates for
|
|
this page.
|
|
This title shouldn\[aq]t contain any HTML tags because the browser
|
|
doesn\[aq]t interpret them correctly.
|
|
Use escape characters on any internal quotation marks within the
|
|
\f[CB]title\f[R] tag.
|
|
If the \f[CB]\-windowtitle\f[R] option is omitted, then the
|
|
\f[CB]javadoc\f[R] tool uses the value of the \f[CB]\-doctitle\f[R] option
|
|
for the \f[CB]\-windowtitle\f[R] option.
|
|
For example,
|
|
\f[CB]javadoc\ \-windowtitle\ "My\ Library"\ com.mypackage\f[R].
|
|
.RS
|
|
.RE
|
|
.SH ADDITIONAL OPTIONS PROVIDED BY THE STANDARD DOCLET
|
|
.PP
|
|
The following are additional options provided by the standard doclet and
|
|
are subject to change without notice.
|
|
Additional options might are less commonly used or are otherwise
|
|
regarded as advanced.
|
|
.TP
|
|
.B \f[CB]\-Xdoclint\f[R]
|
|
Enables recommended checks for problems in Javadoc comments.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-Xdoclint:\f[R](\f[CB]all\f[R]|\f[CB]none\f[R]|[\f[CB]\-\f[R]]\f[I]group\f[R])
|
|
Enable or disable specific checks for bad references, lack of
|
|
accessibility, missing Javadoc comments, and reports errors for invalid
|
|
Javadoc syntax and missing HTML tags.
|
|
.RS
|
|
.PP
|
|
This option enables the \f[CB]javadoc\f[R] tool to check for all
|
|
documentation comments included in the generated output.
|
|
You can select which items to include in the generated output with the
|
|
standard options \f[CB]\-public\f[R], \f[CB]\-protected\f[R],
|
|
\f[CB]\-package\f[R] and \f[CB]\-private\f[R].
|
|
.PP
|
|
When the \f[CB]\-Xdoclint\f[R] is enabled, it reports issues with messages
|
|
similar to the \f[CB]javac\f[R] command.
|
|
The \f[CB]javadoc\f[R] tool prints a message, a copy of the source line,
|
|
and a caret pointing at the exact position where the error was detected.
|
|
Messages may be either warnings or errors, depending on their severity
|
|
and the likelihood to cause an error if the generated documentation were
|
|
run through a validator.
|
|
For example, bad references or missing Javadoc comments don\[aq]t cause
|
|
the \f[CB]javadoc\f[R] tool to generate invalid HTML, so these issues are
|
|
reported as warnings.
|
|
Syntax errors or missing HTML end tags cause the \f[CB]javadoc\f[R] tool
|
|
to generate invalid output, so these issues are reported as errors.
|
|
.PP
|
|
\f[CB]\-Xdoclint\f[R] option validates input comments based upon the
|
|
requested markup.
|
|
.PP
|
|
By default, the \f[CB]\-Xdoclint\f[R] option is enabled.
|
|
Disable it with the option \f[CB]\-Xdoclint:none\f[R].
|
|
.PP
|
|
The following options change what the \f[CB]\-Xdoclint\f[R] option
|
|
reports:
|
|
.IP \[bu] 2
|
|
\f[CB]\-Xdoclint\ none\f[R]: Disables the \f[CB]\-Xdoclint\f[R] option
|
|
.IP \[bu] 2
|
|
\f[CB]\-Xdoclint\f[R] \f[I]group\f[R]: Enables \f[I]group\f[R] checks
|
|
.IP \[bu] 2
|
|
\f[CB]\-Xdoclint\ all\f[R]: Enables all groups of checks
|
|
.IP \[bu] 2
|
|
\f[CB]\-Xdoclint\ all,\-\f[R]\f[I]group\f[R]: Enables all checks except
|
|
\f[I]group\f[R] checks
|
|
.PP
|
|
The \f[I]group\f[R] variable has one of the following values:
|
|
.IP \[bu] 2
|
|
\f[CB]accessibility\f[R]: Checks for the issues to be detected by an
|
|
accessibility checker (for example, no caption or summary attributes
|
|
specified in a \f[CB]<table>\f[R] tag).
|
|
.IP \[bu] 2
|
|
\f[CB]html\f[R]: Detects high\-level HTML issues, such as putting block
|
|
elements inside inline elements, or not closing elements that require an
|
|
end tag.
|
|
The rules are derived from the \f[B]HTML 4 Specification\f[R]
|
|
[https://www.w3.org/TR/html4/] or the \f[B]HTML 5 Specification\f[R]
|
|
[http://www.w3.org/TR/2014/REC\-html5\-20141028/] based on the standard
|
|
doclet \f[CB]html\f[R] output generation selected.
|
|
This type of check enables the \f[CB]javadoc\f[R] tool to detect HTML
|
|
issues that some browsers might not interpret as intended.
|
|
.IP \[bu] 2
|
|
\f[CB]missing\f[R]: Checks for missing Javadoc comments or tags (for
|
|
example, a missing comment or class, or a missing \f[CB]\@return\f[R] tag
|
|
or similar tag on a method).
|
|
.IP \[bu] 2
|
|
\f[CB]reference\f[R]: Checks for issues relating to the references to Java
|
|
API elements from Javadoc tags (for example, item not found in
|
|
\f[CB]\@see\f[R], or a bad name after \f[CB]\@param)\f[R].
|
|
.IP \[bu] 2
|
|
\f[CB]syntax\f[R]: Checks for low level issues like unescaped angle
|
|
brackets (\f[CB]<\f[R] and \f[CB]>\f[R]) and ampersands (\f[CB]&\f[R]) and
|
|
invalid Javadoc tags.
|
|
.PP
|
|
You can specify the \f[CB]\-Xdoclint\f[R] option multiple times to enable
|
|
the option to check errors and warnings in multiple categories.
|
|
Alternatively, you can specify multiple error and warning categories by
|
|
using the preceding options.
|
|
For example, use either of the following commands to check for the HTML,
|
|
syntax, and accessibility issues in the file \f[I]filename\f[R].
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-Xdoclint:html\ \-Xdoclint:syntax\ \-Xdoclint:accessibility\f[R]
|
|
\f[I]filename\f[R]
|
|
.RE
|
|
.RS
|
|
.PP
|
|
\f[CB]javadoc\ \-Xdoclint:html,syntax,accessibility\f[R] \f[I]filename\f[R]
|
|
.RE
|
|
.PP
|
|
\f[B]Note:\f[R]
|
|
.PP
|
|
The \f[CB]javadoc\f[R] tool doesn\[aq]t guarantee the completeness of
|
|
these checks.
|
|
In particular, it isn\[aq]t a full HTML compliance checker.
|
|
The goal of the \-\f[CB]Xdoclint\f[R] option is to enable the
|
|
\f[CB]javadoc\f[R] tool to report majority of common errors.
|
|
.PP
|
|
The \f[CB]javadoc\f[R] tool doesn\[aq]t attempt to fix invalid input, it
|
|
just reports it.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-Xdoclint/package:\f[R][\f[CB]\-\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[CB]*\f[R], which expands to all sub packages of
|
|
the given package.
|
|
Prefix the package specifier with \f[CB]\-\f[R] to disable checks for the
|
|
specified packages.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-Xdocrootparent\f[R] \f[I]url\f[R]
|
|
Replaces all \f[CB]\@docRoot\f[R] items followed by\f[CB]/..\f[R] in Javadoc
|
|
comments with the \f[I]url\f[R].
|
|
.RS
|
|
.RE
|