| .\" Copyright (c) 1994, 2020, 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" "2020" "JDK 15" "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] or \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 Linux 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]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], \f[CB]\-help\f[R], \f[CB]\-h\f[R], or \f[CB]\-?\f[R] |
| Prints a synopsis of the standard options. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-help\-extra\f[R] or \f[CB]\-X\f[R] |
| Prints a synopsis of the set of extra options. |
| .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]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 |
| .TP |
| .B \f[CB]\-Werror\f[R] |
| Reports an error if any warnings occur. |
| .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] |
| .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]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]\-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]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]\-html5\f[R] |
| This option is a no\-op and is just retained for backwards |
| compatibility. |
| .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] |
| This option is a no\-op and is just retained for backwards |
| compatibility. |
| .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]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 are less commonly used or are otherwise regarded as |
| advanced. |
| .TP |
| .B \f[CB]\-Xdoclint\f[R] |
| Enables recommended checks for problems in documentation 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, accessibility |
| issues, missing documentation comments, errors in documentation comment |
| 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] option 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 |
| to be run through a validator. |
| For example: missing documentation comments, duplicate information, and |
| extraneous comments do not cause the \f[CB]javadoc\f[R] tool to generate |
| invalid HTML, so these issues are reported as warnings; syntax errors, |
| missing required HTML end tags, and references to missing or misspelled |
| elements 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 documentation 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 documentation comment 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 documentation comment 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 |