1 .\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
   3 .\"
   4 .\" This code is free software; you can redistribute it and/or modify it
   5 .\" under the terms of the GNU General Public License version 2 only, as
   6 .\" published by the Free Software Foundation.
   7 .\"
   8 .\" This code is distributed in the hope that it will be useful, but WITHOUT
   9 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11 .\" version 2 for more details (a copy is included in the LICENSE file that
  12 .\" accompanied this code).
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License version
  15 .\" 2 along with this work; if not, write to the Free Software Foundation,
  16 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  17 .\"
  18 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  19 .\" or visit www.oracle.com if you need additional information or have any
  20 .\" questions.
  21 .\"
  22 .\" Automatically generated by Pandoc 2.3.1
  23 .\"
  24 .TH "JAVADOC" "1" "2018" "JDK 13" "JDK Commands"
  25 .hy
  26 .SH NAME
  27 .PP
  28 javadoc \- generate HTML pages of API documentation from Java source
  29 files
  31 .PP
  32 \f[CB]javadoc\f[R] [\f[I]options\f[R]] [\f[I]packagenames\f[R]]
  33 [\f[I]sourcefiles\f[R]] [\f[CB]\@\f[R]\f[I]files\f[R]]
  34 .TP
  35 .B \f[I]options\f[R]
  36 Specifies command\-line options, separated by spaces.
  37 See \f[B]Options for javadoc\f[R], \f[B]Extended Options\f[R],
  38 \f[B]Standard doclet Options\f[R], and \f[B]Additional Options Provided
  39 by the Standard doclet\f[R].
  40 .RS
  41 .RE
  42 .TP
  43 .B \f[I]packagenames\f[R]
  44 Specifies names of packages that you want to document, separated by
  45 spaces, for example \f[CB]java.lang\ java.lang.reflect\ java.awt\f[R].
  46 If you want to also document the subpackages, then use the
  47 \f[CB]\-subpackages\f[R] option to specify the packages.
  48 .RS
  49 .PP
  50 By default, \f[CB]javadoc\f[R] looks for the specified packages in the
  51 current directory and subdirectories.
  52 Use the \f[CB]\-sourcepath\f[R] option to specify the list of directories
  53 where to look for packages.
  54 .RE
  55 .TP
  56 .B \f[I]sourcefiles\f[R]
  57 Specifies names of Java source files that you want to document,
  58 separated by spaces, for example
  59 \f[CB]Class.java\ Object.java\ Button.java\f[R].
  60 By default, \f[CB]javadoc\f[R] looks for the specified classes in the
  61 current directory.
  62 However, you can specify the full path to the class file and use
  63 wildcard characters, for example
  64 \f[CB]/home/src/java/awt/Graphics*.java\f[R].
  65 You can also specify the path relative to the current directory.
  66 .RS
  67 .RE
  68 .TP
  69 .B \f[CB]\@\f[R]\f[I]files\f[R]
  70 Specifies names of files that contain a list of \f[CB]javadoc\f[R] tool
  71 options, package names, and source file names in any order.
  72 .RS
  73 .RE
  75 .PP
  76 The \f[CB]javadoc\f[R] tool parses the declarations and documentation
  77 comments in a set of Java source files and produces corresponding HTML
  78 pages that describe (by default) the public and protected classes,
  79 nested classes (but not anonymous inner classes), interfaces,
  80 constructors, methods, and fields.
  81 You can use the \f[CB]javadoc\f[R] tool to generate the API documentation
  82 or the implementation documentation for a set of source files.
  83 .PP
  84 You can run the \f[CB]javadoc\f[R] tool on entire packages, individual
  85 source files, or both.
  86 When documenting entire packages, you can use the \f[CB]\-subpackages\f[R]
  87 option either to recursively traverse a directory and its
  88 subdirectories, or to pass in an explicit list of package names.
  89 When you document individual source files, pass in a list of Java source
  90 file names.
  91 See \f[B]javadoc Overview\f[R]
  92 [https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase/11/tools&id=JSJAV\-GUID\-7A344353\-3BBF\-45C4\-8B28\-15025DDCC643]
  93 in Java Platform, Standard Edition Javadoc Guide for information about
  94 using the \f[CB]javadoc\f[R] tool.
  96 .PP
  97 The standard doclet does not validate the content of documentation
  98 comments for conformance, nor does it attempt to correct any errors in
  99 documentation comments.
 100 Anyone running javadoc is advised to be aware of the problems that may
 101 arise when generating non\-conformant output or output containing
 102 executable content, such as JavaScript.
 103 The standard doclet does provide the \f[CB]doclint\f[R] feature to help
 104 developers detect common problems in documentation comments; but it is
 105 also recommended to check the generated output with any appropriate
 106 conformance and other checking tools.
 107 .PP
 108 For more details on the conformance requirements for HTML5 documents,
 109 see \f[B]Conformance requirements\f[R]
 110 [https://www.w3.org/TR/html5/infrastructure.html#conformance\-requirements]
 111 in the HTML5 Specification.
 112 For more details on security issues related to web pages, see the
 113 \f[B]Open Web Application Security Project (OWASP)\f[R]
 114 [https://www.owasp.org] page.
 116 .PP
 117 The following core \f[CB]javadoc\f[R] options are equivalent to
 118 corresponding \f[CB]javac\f[R] options.
 119 See \f[I]Standard Options\f[R] in \f[B]javac\f[R] for the detailed
 120 descriptions of using these options:
 121 .IP \[bu] 2
 122 \f[CB]\-\-add\-modules\f[R]
 123 .IP \[bu] 2
 124 \f[CB]\-bootclasspath\f[R]
 125 .IP \[bu] 2
 126 \f[CB]\-\-class\-path\f[R], \f[CB]\-classpath\f[R], or \f[CB]\-cp\f[R]
 127 .IP \[bu] 2
 128 \f[CB]\-\-enable\-preview\f[R]
 129 .IP \[bu] 2
 130 \f[CB]\-encoding\f[R]
 131 .IP \[bu] 2
 132 \f[CB]\-extdirs\f[R]
 133 .IP \[bu] 2
 134 \f[CB]\-\-limit\-modules\f[R]
 135 .IP \[bu] 2
 136 \f[CB]\-\-module\f[R]
 137 .IP \[bu] 2
 138 \f[CB]\-\-module\-path\f[R] or \f[CB]\-p\f[R]
 139 .IP \[bu] 2
 140 \f[CB]\-\-module\-source\-path\f[R]
 141 .IP \[bu] 2
 142 \f[CB]\-\-release\f[R]
 143 .IP \[bu] 2
 144 \f[CB]\-source\f[R]
 145 .IP \[bu] 2
 146 \f[CB]\-\-source\-path\f[R] or \f[CB]\-sourcepath\f[R]
 147 .IP \[bu] 2
 148 \f[CB]\-\-system\f[R]
 149 .IP \[bu] 2
 150 \f[CB]\-\-upgrade\-module\-path\f[R]
 151 .PP
 152 The following options are the core \f[CB]javadoc\f[R] options that are not
 153 equivalent to a corresponding \f[CB]javac\f[R] option:
 154 .PP
 155 \f[B]Note:\f[R]
 156 .PP
 157 In tools that support \f[CB]\-\-\f[R] style options, the GNU\-style
 158 options can use the equal sign (=) instead of a white space to separate
 159 the name of an option from its value.
 160 .TP
 161 .B \f[CB]\-breakiterator\f[R]
 162 Computes the first sentence with \f[CB]BreakIterator\f[R].
 163 The first sentence is copied to the package, class, or member summary
 164 and to the alphabetic index.
 165 The \f[CB]BreakIterator\f[R] class is used to determine the end of a
 166 sentence for all languages except for English.
 167 .RS
 168 .IP \[bu] 2
 169 English default sentence\-break algorithm \-\-\- Stops at a period
 170 followed by a space or an HTML block tag, such as \f[CB]<P>\f[R].
 171 .IP \[bu] 2
 172 Breakiterator sentence\-break algorithm \-\-\- Stops at a period,
 173 question mark, or exclamation point followed by a space when the next
 174 word starts with a capital letter.
 175 This is meant to handle most abbreviations (such as "The serial no.
 176 is valid", but will not handle "Mr.\ Smith").
 177 The \f[CB]\-breakiterator\f[R] option doesn\[aq]t stop at HTML tags or
 178 sentences that begin with numbers or symbols.
 179 The algorithm stops at the last period in \f[CB]\&../filename\f[R], even
 180 when embedded in an HTML tag.
 181 .RE
 182 .TP
 183 .B \f[CB]\-doclet\f[R] \f[I]class\f[R]
 184 Generates output by using an alternate doclet.
 185 Use the fully qualified name.
 186 This doclet defines the content and formats the output.
 187 If the \f[CB]\-doclet\f[R] option isn\[aq]t used, then the
 188 \f[CB]javadoc\f[R] tool uses the standard doclet for generating the
 189 default HTML format.
 190 This class must contain the \f[CB]start(Root)\f[R] method.
 191 The path to this starting class is defined by the \f[CB]\-docletpath\f[R]
 192 option.
 193 .RS
 194 .RE
 195 .TP
 196 .B \f[CB]\-docletpath\f[R] \f[I]path\f[R]
 197 Specifies where to find doclet class files (specified with the
 198 \f[CB]\-doclet\f[R] option) and any JAR files it depends on.
 199 If the starting class file is in a JAR file, then this option specifies
 200 the path to that JAR file.
 201 You can specify an absolute path or a path relative to the current
 202 directory.
 203 If \f[CB]classpathlist\f[R] contains multiple paths or JAR files, then
 204 they should be separated with a colon (\f[CB]:\f[R]) on Oracle Solaris and
 205 a semi\-colon (\f[CB];\f[R]) on Windows.
 206 This option isn\[aq]t necessary when the \f[CB]doclet\f[R] starting class
 207 is already in the search path.
 208 .RS
 209 .RE
 210 .TP
 211 .B \f[CB]\-exclude\f[R] \f[I]pkglist\f[R]
 212 Unconditionally, excludes the specified packages and their subpackages
 213 from the list formed by \f[CB]\-subpackages\f[R].
 214 It excludes those packages even when they would otherwise be included by
 215 some earlier or later \f[CB]\-subpackages\f[R] option.
 216 .RS
 217 .PP
 218 The following example would include \f[CB]java.io\f[R],
 219 \f[CB]java.util\f[R], and \f[CB]java.math\f[R] (among others), but would
 220 exclude packages rooted at \f[CB]java.net\f[R] and \f[CB]java.lang\f[R].
 221 Notice that these examples exclude \f[CB]java.lang.ref\f[R], which is a
 222 subpackage of \f[CB]java.lang\f[R].
 223 .IP \[bu] 2
 224 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
 225 .RS 2
 226 .RS
 227 .PP
 228 \f[CB]javadoc\ \-sourcepath\ /home/user/src\ \-subpackages\ java\ \-exclude\ java.net:java.lang\f[R]
 229 .RE
 230 .RE
 231 .IP \[bu] 2
 232 \f[B]Windows:\f[R]
 233 .RS 2
 234 .RS
 235 .PP
 236 \f[CB]javadoc\ \-sourcepath\ \\user\\src\ \-subpackages\ java\ \-exclude\ java.net:java.lang\f[R]
 237 .RE
 238 .RE
 239 .RE
 240 .TP
 241 .B \f[CB]\-\-expand\-requires\f[R] \f[I]value\f[R]
 242 Instructs the javadoc tool to expand the set of modules to be
 243 documented.
 244 By default, only the modules given explicitly on the command line are
 245 documented.
 246 Supports the following values:
 247 .RS
 248 .IP \[bu] 2
 249 \f[CB]transitive\f[R]: additionally includes all the required transitive
 250 dependencies of those modules.
 251 .IP \[bu] 2
 252 \f[CB]all\f[R]: includes all dependencies.
 253 .RE
 254 .TP
 255 .B \f[CB]\-help\f[R] or \f[CB]\-\-help\f[R]
 256 Displays the online help, which lists all of the \f[CB]javadoc\f[R] and
 257 \f[CB]doclet\f[R] command\-line options.
 258 .RS
 259 .RE
 260 .TP
 261 .B \f[CB]\-\-help\-extra\f[R] or \f[CB]\-X\f[R]
 262 Prints a synopsis of non\-standard options and exits.
 263 .RS
 264 .RE
 265 .TP
 266 .B \f[CB]\-J\f[R]\f[I]flag\f[R]
 267 Passes \f[I]flag\f[R] directly to the Java Runtime Environment (JRE) that
 268 runs the \f[CB]javadoc\f[R] tool.
 269 For example, if you must ensure that the system sets aside 32 MB of
 270 memory in which to process the generated documentation, then you would
 271 call the \f[CB]\-Xmx\f[R] option as follows:
 272 \f[CB]javadoc\ \-J\-Xmx32m\ \-J\-Xms32m\ com.mypackage\f[R].
 273 Be aware that \f[CB]\-Xms\f[R] is optional because it only sets the size
 274 of initial memory, which is useful when you know the minimum amount of
 275 memory required.
 276 .RS
 277 .PP
 278 There is no space between the \f[CB]J\f[R] and the \f[CB]flag\f[R].
 279 .PP
 280 Use the \f[CB]\-version\f[R] option to report the version of the JRE being
 281 used to run the \f[CB]javadoc\f[R] tool.
 282 .IP
 283 .nf
 284 \f[CB]
 285 javadoc\ \-J\-version
 286 java\ version\ "10\-ea"\ 2018\-03\-20
 287 Java(TM)\ SE\ Runtime\ Environment\ 18.3\ (build\ 10\-ea+36)
 288 Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ 18.3\ (build\ 10\-ea+36,\ mixed\ mode)
 289 \f[R]
 290 .fi
 291 .RE
 292 .TP
 293 .B \f[CB]\-locale\f[R] \f[I]name\f[R]
 294 Specifies the locale that the \f[CB]javadoc\f[R] tool uses when it
 295 generates documentation.
 296 The argument is the name of the locale, as described in
 297 \f[CB]java.util.Locale\f[R] documentation, such as \f[CB]en_US\f[R]
 298 (English, United States) or \f[CB]en_US_WIN\f[R] (Windows variant).
 299 .RS
 300 .PP
 301 \f[B]Note:\f[R]
 302 .PP
 303 The \f[CB]\-locale\f[R] option must be placed ahead (to the left) of any
 304 options provided by the standard doclet or any other doclet.
 305 Otherwise, the navigation bars appear in English.
 306 This is the only command\-line option that depends on order.
 307 .PP
 308 Specifying a locale causes the \f[CB]javadoc\f[R] tool to choose the
 309 resource files of that locale for messages such as strings in the
 310 navigation bar, headings for lists and tables, help file contents,
 311 comments in the \f[CB]stylesheet.css\f[R] file, and so on.
 312 It also specifies the sorting order for lists sorted alphabetically, and
 313 the sentence separator to determine the end of the first sentence.
 314 The \f[CB]\-locale\f[R] option doesn\[aq]t determine the locale of the
 315 documentation comment text specified in the source files of the
 316 documented classes.
 317 .RE
 318 .TP
 319 .B \f[CB]\-package\f[R]
 320 Shows only package, protected, and public classes and members.
 321 .RS
 322 .RE
 323 .TP
 324 .B \f[CB]\-private\f[R]
 325 Shows all classes and members.
 326 .RS
 327 .RE
 328 .TP
 329 .B \f[CB]\-protected\f[R]
 330 Shows only protected and public classes and members.
 331 This is the default.
 332 .RS
 333 .RE
 334 .TP
 335 .B \f[CB]\-public\f[R]
 336 Shows only the public classes and members.
 337 .RS
 338 .RE
 339 .TP
 340 .B \f[CB]\-quiet\f[R]
 341 Shuts off messages so that only the warnings and errors appear to make
 342 them easier to view.
 343 It also suppresses the \f[CB]version\f[R] string.
 344 .RS
 345 .RE
 346 .TP
 347 .B \f[CB]\-\-show\-members\f[R] \f[I]value\f[R]
 348 Specifies which members (fields or methods) are documented, where
 349 \f[I]value\f[R] can be any of the following:
 350 .RS
 351 .IP \[bu] 2
 352 \f[CB]protected\f[R]: The default value is protected.
 353 .IP \[bu] 2
 354 \f[CB]public\f[R]: Shows only public values.
 355 .IP \[bu] 2
 356 \f[CB]package\f[R]: Shows public, protected, and package members.
 357 .IP \[bu] 2
 358 \f[CB]private\f[R]: Shows all members.
 359 .RE
 360 .TP
 361 .B \f[CB]\-\-show\-module\-contents\f[R] \f[I]value\f[R]
 362 Specifies the documentation granularity of module declarations, where
 363 \f[I]value\f[R] can be \f[CB]api\f[R] or \f[CB]all\f[R].
 364 .RS
 365 .RE
 366 .TP
 367 .B \f[CB]\-\-show\-packages\f[R] \f[I]value\f[R]
 368 Specifies which modules packages are documented, where \f[I]value\f[R]
 369 can be \f[CB]exported\f[R] or \f[CB]all\f[R] packages.
 370 .RS
 371 .RE
 372 .TP
 373 .B \f[CB]\-\-show\-types\f[R] \f[I]value\f[R]
 374 Specifies which types (classes, interfaces, etc.) are documented, where
 375 \f[I]value\f[R] can be any of the following:
 376 .RS
 377 .IP \[bu] 2
 378 \f[CB]protected\f[R]: The default value.
 379 Shows public and protected types.
 380 .IP \[bu] 2
 381 \f[CB]public\f[R]: Shows only public values.
 382 .IP \[bu] 2
 383 \f[CB]package\f[R]: Shows public, protected, and package types.
 384 .IP \[bu] 2
 385 \f[CB]private\f[R]: Shows all types.
 386 .RE
 387 .TP
 388 .B \f[CB]\-subpackages\f[R] \f[I]subpkglist\f[R]
 389 Generates documentation from source files in the specified packages and
 390 recursively in their subpackages.
 391 This option is useful when adding new subpackages to the source code
 392 because they are automatically included.
 393 Each package argument is any top\-level subpackage (such as
 394 \f[CB]java\f[R]) or fully qualified package (such as \f[CB]javax.swing\f[R])
 395 that doesn\[aq]t need to contain source files.
 396 Arguments are separated by colons on all operating systems.
 397 Wild cards aren\[aq]t allowed.
 398 Use \f[CB]\-sourcepath\f[R] to specify where to find the packages.
 399 This option doesn\[aq]t process source files that are in the source tree
 400 but don\[aq]t belong to the packages.
 401 .RS
 402 .PP
 403 For example, the following commands generates documentation for packages
 404 named \f[CB]java\f[R] and \f[CB]javax.swing\f[R] and all of their
 405 subpackages.
 406 .IP \[bu] 2
 407 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
 408 .RS 2
 409 .RS
 410 .PP
 411 \f[CB]javadoc\ \-d\ docs\ \-sourcepath\ /home/user/src\ \-subpackages\ java:javax.swing\f[R]
 412 .RE
 413 .RE
 414 .IP \[bu] 2
 415 \f[B]Windows:\f[R]
 416 .RS 2
 417 .RS
 418 .PP
 419 \f[CB]javadoc\ \-d\ docs\ \-sourcepath\ \\user\\src\ \-subpackages\ java:javax.swing\f[R]
 420 .RE
 421 .RE
 422 .RE
 423 .TP
 424 .B \f[CB]\-verbose\f[R]
 425 Provides more detailed messages while the \f[CB]javadoc\f[R] tool runs.
 426 Without the \f[CB]\-verbose\f[R] option, messages appear for loading the
 427 source files, generating the documentation (one message per source
 428 file), and sorting.
 429 The \f[CB]\-verbose\f[R] option causes the printing of additional messages
 430 that specify the number of milliseconds to parse each Java source file.
 431 .RS
 432 .RE
 433 .TP
 434 .B \f[CB]\-\-version\f[R]
 435 Prints version information.
 436 .RS
 437 .RE
 439 .PP
 440 \f[B]Note:\f[R]
 441 .PP
 442 The extended options for \f[CB]javadoc\f[R] are subject to change without
 443 notice.
 444 .PP
 445 The following extended \f[CB]javadoc\f[R] options are equivalent to
 446 corresponding \f[CB]javac\f[R] options.
 447 See \f[I]Extra Options\f[R] in \f[B]javac\f[R] for the detailed
 448 descriptions of using these options:
 449 .IP \[bu] 2
 450 \f[CB]\-add\-exports\f[R]
 451 .IP \[bu] 2
 452 \f[CB]\-\-add\-reads\f[R]
 453 .IP \[bu] 2
 454 \f[CB]\-\-patch\-module\f[R]
 455 .IP \[bu] 2
 456 \f[CB]\-\-Xmaxerrs\f[R]
 457 .IP \[bu] 2
 458 \f[CB]\-Xmaxwarns\f[R]
 459 .PP
 460 The following extended \f[CB]javadoc\f[R] options are not equivalent to a
 461 corresponding \f[CB]javac\f[R] option:
 462 .TP
 463 .B \f[CB]\-Xmodule:\f[R]\f[I]module\-name\f[R]
 464 Specifies a module to which the classes being compiled belong.
 465 .RS
 466 .RE
 467 .TP
 468 .B \f[CB]\-Xold\f[R]
 469 Invokes the legacy javadoc tool.
 470 .RS
 471 .RE
 473 .PP
 474 The following options are provided by the standard doclet.
 475 .TP
 476 .B \f[CB]\-\-add\-stylesheet\f[R] \f[I]file\f[R]
 477 Adds additional stylesheet file for the generated documentation.
 478 This option can be used one or more times to specify additional
 479 stylesheets included in the documentation.
 480 .RS
 481 .PP
 482 Command\-line example:
 483 .RS
 484 .PP
 485 \f[CB]javadoc\ \-\-add\-stylesheet\ new_stylesheet_1.css\ \-\-add\-stylesheet\ new_stylesheet_2.css\ pkg_foo\f[R]
 486 .RE
 487 .RE
 488 .TP
 489 .B \f[CB]\-\-allow\-script\-in\-comments\f[R]
 490 Allow JavaScript in options and comments
 491 .RS
 492 .RE
 493 .TP
 494 .B \f[CB]\-author\f[R]
 495 Includes the \f[CB]\@author\f[R] text in the generated docs.
 496 .RS
 497 .RE
 498 .TP
 499 .B \f[CB]\-bottom\f[R] \f[I]html\-code\f[R]
 500 Specifies the text to be placed at the bottom of each output file.
 501 The text is placed at the bottom of the page, underneath the lower
 502 navigation bar.
 503 The text can contain HTML tags and white space, but when it does, the
 504 text must be enclosed in quotation marks.
 505 Use escape characters for any internal quotation marks within text.
 506 .RS
 507 .RE
 508 .TP
 509 .B \f[CB]\-charset\f[R] \f[I]name\f[R]
 510 Specifies the HTML character set for this document.
 511 The name should be a preferred MIME name as specified in the \f[B]IANA
 512 Registry, Character Sets\f[R]
 513 [http://www.iana.org/assignments/character\-sets].
 514 .RS
 515 .PP
 516 For example:
 517 .RS
 518 .PP
 519 \f[CB]javadoc\ \-charset\ "iso\-8859\-1"\ mypackage\f[R]
 520 .RE
 521 .PP
 522 This command inserts the following line in the head of every generated
 523 page:
 524 .RS
 525 .PP
 526 \f[CB]<META\ http\-equiv="Content\-Type"\ content="text/html;\ charset=ISO\-8859\-1">\f[R]
 527 .RE
 528 .PP
 529 The \f[CB]META\f[R] tag is described in the \f[B]HTML standard (4197265
 530 and 4137321), HTML Document Representation\f[R]
 531 [http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2].
 532 .RE
 533 .TP
 534 .B \f[CB]\-d\f[R] \f[I]directory\f[R]
 535 Specifies the destination directory where the \f[CB]javadoc\f[R] tool
 536 saves the generated HTML files.
 537 If you omit the \f[CB]\-d\f[R] option, then the files are saved to the
 538 current directory.
 539 The \f[CB]directory\f[R] value can be absolute or relative to the current
 540 working directory.
 541 The destination directory is automatically created when the
 542 \f[CB]javadoc\f[R] tool runs.
 543 .RS
 544 .IP \[bu] 2
 545 \f[B]Oracle Solaris, Linux, and OS X:\f[R] For example, the following
 546 command generates the documentation for the package
 547 \f[CB]com.mypackage\f[R] and saves the results in the \f[CB]/user/doc/\f[R]
 548 directory:
 549 .RS 2
 550 .RS
 551 .PP
 552 \f[CB]javadoc\ \-d\ /user/doc/\ com.mypackage\f[R]
 553 .RE
 554 .RE
 555 .IP \[bu] 2
 556 \f[B]Windows:\f[R] For example, the following command generates the
 557 documentation for the package \f[CB]com.mypackage\f[R] and saves the
 558 results in the \f[CB]\\user\\doc\\\f[R] directory:
 559 .RS 2
 560 .RS
 561 .PP
 562 \f[CB]javadoc\ \-d\ \\user\\doc\\\ com.mypackage\f[R]
 563 .RE
 564 .RE
 565 .RE
 566 .TP
 567 .B \f[CB]\-docencoding\f[R] \f[I]name\f[R]
 568 Specifies the encoding of the generated HTML files.
 569 The name should be a preferred MIME name as specified in the \f[B]IANA
 570 Registry, Character Sets\f[R]
 571 [http://www.iana.org/assignments/character\-sets].
 572 .RS
 573 .PP
 574 Three options are available for use in a \f[CB]javadoc\f[R] encoding
 575 command.
 576 The \f[CB]\-encoding\f[R] option is used for encoding the files read by
 577 the \f[CB]javadoc\f[R] tool, while the \f[CB]\-docencoding\f[R] and
 578 \f[CB]\-charset\f[R] options are used for encoding the files written by
 579 the tool.
 580 Of the three available options, at most, only the input and an output
 581 encoding option are used in a single encoding command.
 582 If you specify both input and output encoding options in a command, they
 583 must be the same value.
 584 If you specify neither output option, it the tool defaults to the input
 585 encoding.
 586 .PP
 587 For example:
 588 .RS
 589 .PP
 590 \f[CB]javadoc\ \-docencoding\ "iso\-8859\-1"\ mypackage\f[R]
 591 .RE
 592 .RE
 593 .TP
 594 .B \f[CB]\-docfilessubdirs\f[R]
 595 Recursively copies doc\-file subdirectories.
 596 .RS
 597 .RE
 598 .TP
 599 .B \f[CB]\-doctitle\f[R] \f[I]html\-code\f[R]
 600 Specifies the title to place near the top of the overview summary file.
 601 The text specified in the \f[CB]title\f[R] tag is placed as a centered,
 602 level\-one heading directly beneath the top navigation bar.
 603 The \f[CB]title\f[R] tag can contain HTML tags and white space, but when
 604 it does, you must enclose the title in quotation marks.
 605 Additional quotation marks within the \f[CB]title\f[R] tag must be
 606 escaped.
 607 For example,
 608 \f[CB]javadoc\ \-header\ "<b>My\ Library</b><br>v1.0"\ com.mypackage.\f[R]
 609 .RS
 610 .RE
 611 .TP
 612 .B \f[CB]\-excludedocfilessubdir\f[R] \f[I]name\f[R]
 613 Excludes any doc files sub directories with the given name.
 614 Enables deep copying of doc\-files directories.
 615 Subdirectories and all contents are recursively copied to the
 616 destination.
 617 For example, the directory \f[CB]doc\-files/example/images\f[R] and all of
 618 its contents are copied.
 619 There is also an option to exclude subdirectories.
 620 .RS
 621 .RE
 622 .TP
 623 .B \f[CB]\-footer\f[R] \f[I]html\-code\f[R]
 624 Specifies the footer text to be placed at the bottom of each output
 625 file.
 626 The\f[CB]html\-code\f[R] value is placed to the right of the lower
 627 navigation bar.
 628 The \f[CB]html\-code\f[R] value can contain HTML tags and white space, but
 629 when it does, the \f[CB]html\-code\f[R] value must be enclosed in
 630 quotation marks.
 631 Use escape characters for any internal quotation marks within a footer.
 632 .RS
 633 .RE
 634 .TP
 635 .B \f[CB]\-\-frames\f[R]
 636 Enables the use of frames in the generated output (default).
 637 .RS
 638 .RE
 639 .TP
 640 .B \f[CB]\-group\f[R] \f[I]namep1\f[R]\f[CB]:\f[R]\f[I]p2\f[R]
 641 Group the specified packages together in the Overview page.
 642 .RS
 643 .RE
 644 .TP
 645 .B \f[CB]\-header\f[R] \f[I]html\-code\f[R]
 646 Specifies the header text to be placed at the top of each output file.
 647 The header is placed to the right of the upper navigation bar.
 648 The \f[CB]header\f[R] can contain HTML tags and white space, but when it
 649 does, the \f[CB]header\f[R] must be enclosed in quotation marks.
 650 Use escape characters for internal quotation marks within a header.
 651 For example,
 652 \f[CB]javadoc\ \-header\ "<b>My\ Library</b><br>v1.0"\ com.mypackage.\f[R]
 653 .RS
 654 .RE
 655 .TP
 656 .B \f[CB]\-helpfile\f[R] \f[I]filename\f[R]
 657 Includes the file that links to the \f[B]HELP\f[R] link in the top and
 658 bottom navigation bars .
 659 Without this option, the \f[CB]javadoc\f[R] tool creates a help file
 660 \f[CB]help\-doc.html\f[R] that is hard\-coded in the \f[CB]javadoc\f[R]
 661 tool.
 662 This option lets you override the default.
 663 The \f[I]filename\f[R] can be any name and isn\[aq]t restricted to
 664 \f[CB]help\-doc.html\f[R].
 665 The \f[CB]javadoc\f[R] tool adjusts the links in the navigation bar
 666 accordingly.
 667 For example:
 668 .RS
 669 .IP \[bu] 2
 670 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
 671 .RS 2
 672 .RS
 673 .PP
 674 \f[CB]javadoc\ \-helpfile\ /home/user/myhelp.html\ java.awt.\f[R]
 675 .RE
 676 .RE
 677 .IP \[bu] 2
 678 \f[B]Windows:\f[R]
 679 .RS 2
 680 .RS
 681 .PP
 682 \f[CB]javadoc\ \-helpfile\ C:\\user\\myhelp.html\ java.awt.\f[R]
 683 .RE
 684 .RE
 685 .RE
 686 .TP
 687 .B \f[CB]\-html4\f[R]
 688 Generates HTML 4.0.1 output.
 689 If the option is not used, \f[CB]\-html4\f[R] is the default
 690 .RS
 691 .RE
 692 .TP
 693 .B \f[CB]\-html5\f[R]
 694 Generates HTML 5 output.
 695 If the option is not used, \f[CB]\-html4\f[R] is the default.
 696 .RS
 697 .RE
 698 .TP
 699 .B \f[CB]\-\-javafx\f[R] or \f[CB]\-javafx\f[R]
 700 Enables JavaFX functionality.
 701 .RS
 702 .RE
 703 .TP
 704 .B \f[CB]\-keywords\f[R]
 705 Adds HTML keyword \f[CB]<META>\f[R] tags to the generated file for each
 706 class.
 707 These tags can help search engines that look for \f[CB]<META>\f[R] tags
 708 find the pages.
 709 Most search engines that search the entire Internet don\[aq]t look at
 710 \f[CB]<META>\f[R] tags, because pages can misuse them.
 711 Search engines offered by companies that confine their searches to their
 712 own website can benefit by looking at \f[CB]<META>\f[R] tags.
 713 The \f[CB]<META>\f[R] tags include the fully qualified name of the class
 714 and the unqualified names of the fields and methods.
 715 Constructors aren\[aq]t included because they are identical to the class
 716 name.
 717 For example, the class \f[CB]String\f[R] starts with these keywords:
 718 .RS
 719 .IP
 720 .nf
 721 \f[CB]
 722 <META\ NAME="keywords"\ CONTENT="java.lang.String\ class">
 724 <META\ NAME="keywords"\ CONTENT="length()">
 725 <META\ NAME="keywords"\ CONTENT="charAt()">
 726 \f[R]
 727 .fi
 728 .RE
 729 .TP
 730 .B \f[CB]\-link\f[R] \f[I]url\f[R]
 731 Creates links to existing \f[CB]javadoc\f[R] generated documentation of
 732 externally referenced classes.
 733 The \f[I]url\f[R] argument is the absolute or relative URL of the
 734 directory that contains the external \f[CB]javadoc\f[R] generated
 735 documentation.
 736 You can specify multiple \f[CB]\-link\f[R] options in a specified
 737 \f[CB]javadoc\f[R] tool run to link to multiple documents.
 738 .RS
 739 .PP
 740 Either a \f[CB]package\-list\f[R] or an \f[CB]element\-list\f[R] file must
 741 be in this \f[I]url\f[R] directory (otherwise, use the
 742 \f[CB]\-linkoffline\f[R] option).
 743 .PP
 744 \f[B]Note:\f[R]
 745 .PP
 746 The \f[CB]package\-list\f[R] and \f[CB]element\-list\f[R] files are
 747 generated by the \f[CB]javadoc\f[R] tool when generating the API
 748 documentation and should not be modified by the user.
 749 .PP
 750 When you use the \f[CB]javadoc\f[R] tool to document packages, it uses the
 751 \f[CB]package\-list\f[R] file to determine the packages declared in an
 752 API.
 753 When you generate API documents for modules, the \f[CB]javadoc\f[R] tool
 754 uses the \f[CB]element\-list\f[R] file to determine the modules and
 755 packages declared in an API.
 756 .PP
 757 The \f[CB]javadoc\f[R] tool reads the names from the appropriate list file
 758 and then links to the packages or modules at that URL.
 759 .PP
 760 When the \f[CB]javadoc\f[R] tool runs, the \f[I]url\f[R] value is copied
 761 into the \f[CB]<A\ HREF>\f[R] links that are created.
 762 Therefore, \f[I]url\f[R] must be the URL to the directory and not to a
 763 file.
 764 .PP
 765 You can use an absolute link for \f[I]url\f[R] to enable your documents
 766 to link to a document on any web site, or you can use a relative link to
 767 link only to a relative location.
 768 If you use a relative link, then the value you pass in should be the
 769 relative path from the destination directory (specified with the
 770 \f[CB]\-d\f[R] option) to the directory containing the packages being
 771 linked to.
 772 When you specify an absolute link, you usually use an HTTP link.
 773 However, if you want to link to a file system that has no web server,
 774 then you can use a file link.
 775 Use a file link only when everyone who wants to access the generated
 776 documentation shares the same file system.
 777 In all cases, and on all operating systems, use a slash as the
 778 separator, whether the URL is absolute or relative, and \f[CB]https:\f[R],
 779 \f[CB]http:\f[R], or \f[CB]file:\f[R] as specified in the \f[B]URL Memo:
 780 Uniform Resource Locators\f[R] [http://www.ietf.org/rfc/rfc1738.txt].
 781 .IP
 782 .nf
 783 \f[CB]
 784 \-link\ https://<host>/<directory>/<directory>/.../<name>
 785 \-link\ http://<host>/<directory>/<directory>/.../<name>
 786 \-link\ file://<host>/<directory>/<directory>/.../<name>
 787 \-link\ <directory>/<directory>/.../<name>
 788 \f[R]
 789 .fi
 790 .RE
 791 .TP
 792 .B \f[CB]\-linkoffline\f[R] \f[I]url1\f[R] \f[I]url2\f[R]
 793 This option is a variation of the \f[CB]\-link\f[R] option.
 794 They both create links to \f[CB]javadoc\f[R] generated documentation for
 795 externally referenced classes.
 796 You can specify multiple \f[CB]\-linkoffline\f[R] options in a specified
 797 \f[CB]javadoc\f[R] tool run.
 798 .RS
 799 .PP
 800 Use the \f[CB]\-linkoffline\f[R] option when:
 801 .IP \[bu] 2
 802 Linking to a document on the web that the \f[CB]javadoc\f[R] tool
 803 can\[aq]t access through a web connection
 804 .IP \[bu] 2
 805 The \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R] file of the
 806 external document either isn\[aq]t accessible or doesn\[aq]t exist at
 807 the URL location, but does exist at a different location and can be
 808 specified by either the \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R]
 809 file (typically local).
 810 .PP
 811 \f[B]Note:\f[R]
 812 .PP
 813 The \f[CB]package\-list\f[R] and \f[CB]element\-list\f[R] files are
 814 generated by the \f[CB]javadoc\f[R] tool when generating the API
 815 documentation and should not be modified by the user.
 816 .PP
 817 If \f[I]url1\f[R] is accessible only on the World Wide Web, then the
 818 \f[CB]\-linkoffline\f[R] option removes the constraint that the
 819 \f[CB]javadoc\f[R] tool must have a web connection to generate
 820 documentation.
 821 .PP
 822 Another use of the \f[CB]\-linkoffline\f[R] option is as a work\-around to
 823 update documents.
 824 After you have run the \f[CB]javadoc\f[R] tool on a full set of packages
 825 or modules, you can run the \f[CB]javadoc\f[R] tool again on a smaller set
 826 of changed packages or modules, so that the updated files can be
 827 inserted back into the original set.
 828 .PP
 829 For example, the \f[CB]\-linkoffline\f[R] option takes two arguments.
 830 The first is for the string to be embedded in the \f[CB]<a\ href>\f[R]
 831 links, and the second tells the \f[CB]javadoc\f[R] tool where to find
 832 either the \f[CB]package\-list\f[R] or \f[CB]element\-list\f[R] file.
 833 .PP
 834 The \f[I]url1\f[R] or \f[I]url2\f[R] value is the absolute or relative URL
 835 of the directory that contains the external \f[CB]javadoc\f[R] generated
 836 documentation that you want to link to.
 837 When relative, the value should be the relative path from the
 838 destination directory (specified with the \f[CB]\-d\f[R] option) to the
 839 root of the packages being linked to.
 840 See \f[I]url\f[R] in the \f[CB]\-link\f[R] option.
 841 .RE
 842 .TP
 843 .B \f[CB]\-linksource\f[R]
 844 Creates an HTML version of each source file (with line numbers) and adds
 845 links to them from the standard HTML documentation.
 846 Links are created for classes, interfaces, constructors, methods, and
 847 fields whose declarations are in a source file.
 848 Otherwise, links aren\[aq]t created, such as for default constructors
 849 and generated classes.
 850 .RS
 851 .PP
 852 This option exposes all private implementation details in the included
 853 source files, including private classes, private fields, and the bodies
 854 of private methods, regardless of the \f[CB]\-public\f[R],
 855 \f[CB]\-package\f[R], \f[CB]\-protected\f[R], and \f[CB]\-private\f[R]
 856 options.
 857 Unless you also use the \f[CB]\-private\f[R] option, not all private
 858 classes or interfaces are accessible through links.
 859 .PP
 860 Each link appears on the name of the identifier in its declaration.
 861 For example, the link to the source code of the \f[CB]Button\f[R] class
 862 would be on the word \f[CB]Button\f[R]:
 863 .RS
 864 .PP
 865 \f[CB]public\ class\ Button\ extends\ Component\ implements\ Accessible\f[R]
 866 .RE
 867 .PP
 868 The link to the source code of the \f[CB]getLabel\f[R] method in the
 869 \f[CB]Button\f[R] class is on the word \f[CB]getLabel\f[R]:
 870 .RS
 871 .PP
 872 \f[CB]public\ String\ getLabel()\f[R]
 873 .RE
 874 .RE
 875 .TP
 876 .B \f[CB]\-\-main\-stylesheet\f[R] \f[I]file\f[R] or \f[CB]\-stylesheetfile\f[R] \f[I]file\f[R]
 877 Specifies the path of an alternate stylesheet file that contains the
 878 definitions for the CSS styles used in the generated documentation.
 879 This option lets you override the default.
 880 If you do not specify the option, the \f[CB]javadoc\f[R] tool will create
 881 and use a default stylesheet.
 882 The file name can be any name and isn\[aq]t restricted to
 883 \f[CB]stylesheet.css\f[R].
 884 The \f[CB]\-\-main\-stylesheet\f[R] option is the preferred form.
 885 .RS
 886 .PP
 887 Command\-line example:
 888 .RS
 889 .PP
 890 \f[CB]javadoc\ \-\-main\-stylesheet\ main_stylesheet.css\ pkg_foo\f[R]
 891 .RE
 892 .RE
 893 .TP
 894 .B \f[CB]\-nocomment\f[R]
 895 Suppresses the entire comment body, including the main description and
 896 all tags, and generate only declarations.
 897 This option lets you reuse source files that were originally intended
 898 for a different purpose so that you can produce skeleton HTML
 899 documentation during the early stages of a new project.
 900 .RS
 901 .RE
 902 .TP
 903 .B \f[CB]\-nodeprecated\f[R]
 904 Prevents the generation of any deprecated API in the documentation.
 905 This does what the \f[CB]\-nodeprecatedlist\f[R] option does, and it
 906 doesn\[aq]t generate any deprecated API throughout the rest of the
 907 documentation.
 908 This is useful when writing code when you don\[aq]t want to be
 909 distracted by the deprecated code.
 910 .RS
 911 .RE
 912 .TP
 913 .B \f[CB]\-nodeprecatedlist\f[R]
 914 Prevents the generation of the file that contains the list of deprecated
 915 APIs (\f[CB]deprecated\-list.html\f[R]) and the link in the navigation bar
 916 to that page.
 917 The \f[CB]javadoc\f[R] tool continues to generate the deprecated API
 918 throughout the rest of the document.
 919 This is useful when your source code contains no deprecated APIs, and
 920 you want to make the navigation bar cleaner.
 921 .RS
 922 .RE
 923 .TP
 924 .B \f[CB]\-\-no\-frames\f[R]
 925 Disables the use of frames in the generated output.
 926 .RS
 927 .RE
 928 .TP
 929 .B \f[CB]\-nohelp\f[R]
 930 Omits the HELP link in the navigation bars at the top and bottom of each
 931 page of output.
 932 .RS
 933 .RE
 934 .TP
 935 .B \f[CB]\-noindex\f[R]
 936 Omits the index from the generated documents.
 937 The index is produced by default.
 938 .RS
 939 .RE
 940 .TP
 941 .B \f[CB]\-nonavbar\f[R]
 942 Prevents the generation of the navigation bar, header, and footer, that
 943 are usually found at the top and bottom of the generated pages.
 944 The \f[CB]\-nonavbar\f[R] option has no affect on the \f[CB]\-bottom\f[R]
 945 option.
 946 The \f[CB]\-nonavbar\f[R] option is useful when you are interested only in
 947 the content and have no need for navigation, such as when you are
 948 converting the files to PostScript or PDF for printing only.
 949 .RS
 950 .RE
 951 .TP
 952 .B \f[CB]\-noqualifier\f[R] \f[I]name1\f[R]\f[CB]:\f[R]\f[I]name2\f[R]...
 953 Excludes the list of qualifiers from the output.
 954 The package name is removed from places where class or interface names
 955 appear.
 956 .RS
 957 .PP
 958 The following example omits all package qualifiers:
 959 \f[CB]\-noqualifier\ all\f[R].
 960 .PP
 961 The following example omits \f[CB]java.lang\f[R] and \f[CB]java.io\f[R]
 962 package qualifiers: \f[CB]\-noqualifier\ java.lang:java.io\f[R].
 963 .PP
 964 The following example omits package qualifiers starting with
 965 \f[CB]java\f[R] and \f[CB]com.sun\f[R] subpackages, but not
 966 \f[CB]javax:\ \-noqualifier\ java.*:com.sun.*\f[R].
 967 .PP
 968 Where a package qualifier would appear due to the previous behavior, the
 969 name can be suitably shortened.
 970 This rule is in effect whether or not the \f[CB]\-noqualifier\f[R] option
 971 is used.
 972 .RE
 973 .TP
 974 .B \f[CB]\-nosince\f[R]
 975 Omits from the generated documents the \f[CB]Since\f[R] sections
 976 associated with the \f[CB]\@since\f[R] tags.
 977 .RS
 978 .RE
 979 .TP
 980 .B \f[CB]\-notimestamp\f[R]
 981 Suppresses the time stamp, which is hidden in an HTML comment in the
 982 generated HTML near the top of each page.
 983 The \f[CB]\-notimestamp\f[R] option is useful when you want to run the
 984 \f[CB]javadoc\f[R] tool on two source bases and get the differences
 985 between \f[CB]diff\f[R] them, because it prevents time stamps from causing
 986 a \f[CB]diff\f[R] (which would otherwise be a \f[CB]diff\f[R] on every
 987 page).
 988 The time stamp includes the \f[CB]javadoc\f[R] tool release number.
 989 .RS
 990 .RE
 991 .TP
 992 .B \f[CB]\-notree\f[R]
 993 Omits the class and interface hierarchy pages from the generated
 994 documents.
 995 These are the pages you reach using the Tree button in the navigation
 996 bar.
 997 The hierarchy is produced by default.
 998 .RS
 999 .RE
1000 .TP
1001 .B \f[CB]\-\-override\-methods\f[R] (\f[CB]detail\f[R]|\f[CB]summary\f[R])
1002 Documents overridden methods in the detail or summary sections.
1003 .RS
1004 .RE
1005 .TP
1006 .B \f[CB]\-overview\f[R] \f[I]filename\f[R]
1007 Specifies that the \f[CB]javadoc\f[R] tool should retrieve the text for
1008 the overview documentation from the source file specified by
1009 \f[CB]filename\f[R] and place it on the Overview page
1010 (\f[CB]overview\-summary.html\f[R]).
1011 A relative path specified with the file name is relative to the current
1012 working directory.
1013 .RS
1014 .PP
1015 While you can use any name you want for the \f[CB]filename\f[R] value and
1016 place it anywhere you want for the path, it is typical to name it
1017 \f[CB]overview.html\f[R] and place it in the source tree at the directory
1018 that contains the topmost package directories.
1019 In this location, no path is needed when documenting packages, because
1020 the \f[CB]\-sourcepath\f[R] option points to this file.
1021 .IP \[bu] 2
1022 \f[B]Oracle Solaris, Linux, and OS X:\f[R] For example, if the source
1023 tree for the \f[CB]java.lang\f[R] package is
1024 \f[CB]/src/classes/java/lang/\f[R], then you could place the overview file
1025 at /src/classes/overview.html.
1026 .IP \[bu] 2
1027 \f[B]Windows:\f[R] For example, if the source tree for the
1028 \f[CB]java.lang\f[R] package is \f[CB]\\src\\classes\\java\\lang\\\f[R],
1029 then you could place the overview file at
1030 \f[CB]\\src\\classes\\overview.html\f[R]
1031 .PP
1032 The overview page is created only when you pass two or more package
1033 names to the \f[CB]javadoc\f[R] tool.
1034 The title on the overview page is set by \f[CB]\-doctitle\f[R].
1035 .RE
1036 .TP
1037 .B \f[CB]\-serialwarn\f[R]
1038 Generates compile\-time warnings for missing \f[CB]\@serial\f[R] tags.
1039 By default, Javadoc generates no serial warnings.
1040 Use this option to display the serial warnings, which helps to properly
1041 document default serializable fields and \f[CB]writeExternal\f[R] methods.
1042 .RS
1043 .RE
1044 .TP
1045 .B \f[CB]\-sourcetab\f[R] \f[I]tablength\f[R]
1046 Specifies the number of spaces each tab uses in the source.
1047 .RS
1048 .RE
1049 .TP
1050 .B \f[CB]\-splitindex\f[R]
1051 Splits the index file into multiple files, alphabetically, one file per
1052 letter, plus a file for any index entries that start with
1053 non\-alphabetical symbols.
1054 .RS
1055 .RE
1056 .TP
1057 .B \f[CB]\-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
1058 Specifies single argument custom tags.
1059 For the \f[CB]javadoc\f[R] tool to spell\-check tag names, it is important
1060 to include a \f[CB]\-tag\f[R] option for every custom tag that is present
1061 in the source code, disabling (with \f[CB]X\f[R]) those that aren\[aq]t
1062 being output in the current run.
1063 The colon (\f[CB]:\f[R]) is always the separator.
1064 The \f[CB]\-tag\f[R] option outputs the tag heading, \f[I]header\f[R], in
1065 bold, followed on the next line by the text from its single argument.
1066 Similar to any block tag, the argument text can contain inline tags,
1067 which are also interpreted.
1068 The output is similar to standard one\-argument tags, such as the
1069 \f[CB]\@return\f[R] and \f[CB]\@author\f[R] tags.
1070 Omitting a \f[I]header\f[R] value causes the \f[I]name\f[R] to be the
1071 heading.
1072 .RS
1073 .RE
1074 .TP
1075 .B \f[CB]\-taglet\f[R] \f[I]class\f[R]
1076 Specifies the fully qualified name of the taglet used in generating the
1077 documentation for that tag.
1078 Use the fully qualified name for the \f[I]class\f[R] value.
1079 This taglet also defines the number of text arguments that the custom
1080 tag has.
1081 The taglet accepts those arguments, processes them, and generates the
1082 output.
1083 .RS
1084 .PP
1085 Taglets are useful for block or inline tags.
1086 They can have any number of arguments and implement custom behavior,
1087 such as making text bold, formatting bullets, writing out the text to a
1088 file, or starting other processes.
1089 Taglets can only determine where a tag should appear and in what form.
1090 All other decisions are made by the doclet.
1091 A taglet can\[aq]t do things such as remove a class name from the list
1092 of included classes.
1093 However, it can execute side effects, such as printing the tag\[aq]s
1094 text to a file or triggering another process.
1095 Use the \f[CB]\-tagletpath\f[R] option to specify the path to the taglet.
1096 The following example inserts the To Do taglet after Parameters and
1097 ahead of Throws in the generated pages.
1098 .IP
1099 .nf
1100 \f[CB]
1101 \-taglet\ com.sun.tools.doclets.ToDoTaglet
1102 \-tagletpath\ /home/taglets
1103 \-tag\ return
1104 \-tag\ param
1105 \-tag\ todo
1106 \-tag\ throws
1107 \-tag\ see
1108 \f[R]
1109 .fi
1110 .PP
1111 Alternately, you can use the \f[CB]\-taglet\f[R] option in place of its
1112 \f[CB]\-tag\f[R] option, but that might be difficult to read.
1113 .RE
1114 .TP
1115 .B \f[CB]\-tagletpath\f[R] \f[I]tagletpathlist\f[R]
1116 Specifies the search paths for finding taglet class files.
1117 The \f[I]tagletpathlist\f[R] can contain multiple paths by separating
1118 them with a colon (\f[CB]:\f[R]).
1119 The \f[CB]javadoc\f[R] tool searches all subdirectories of the specified
1120 paths.
1121 .RS
1122 .RE
1123 .TP
1124 .B \f[CB]\-top\f[R] \f[I]html\-code\f[R]
1125 Specifies the text to be placed at the top of each output file.
1126 .RS
1127 .RE
1128 .TP
1129 .B \f[CB]\-use\f[R]
1130 Creates class and package usage pages.
1131 Includes one Use page for each documented class and package.
1132 The page describes what packages, classes, methods, constructors and
1133 fields use any API of the specified class or package.
1134 Given class C, things that use class C would include subclasses of C,
1135 fields declared as C, methods that return C, and methods and
1136 constructors with parameters of type C.
1137 For example, you can look at the Use page for the \f[CB]String\f[R] type.
1138 Because the \f[CB]getName\f[R] method in the \f[CB]java.awt.Font\f[R] class
1139 returns type \f[CB]String\f[R], the \f[CB]getName\f[R] method uses
1140 \f[CB]String\f[R] and so the \f[CB]getName\f[R] method appears on the Use
1141 page for \f[CB]String\f[R].
1142 This documents only uses of the API, not the implementation.
1143 When a method uses \f[CB]String\f[R] in its implementation, but
1144 doesn\[aq]t take a string as an argument or return a string, that
1145 isn\[aq]t considered a use of \f[CB]String\f[R].To access the generated
1146 Use page, go to the class or package and click the \f[B]Use link\f[R] in
1147 the navigation bar.
1148 .RS
1149 .RE
1150 .TP
1151 .B \f[CB]\-version\f[R]
1152 Includes the version text in the generated docs.
1153 This text is omitted by default.
1154 To find out what version of the \f[CB]javadoc\f[R] tool you are using, use
1155 the \f[CB]\-J\-version\f[R] option.
1156 .RS
1157 .RE
1158 .TP
1159 .B \f[CB]\-windowtitle\f[R] \f[I]title\f[R]
1160 Specifies the title to be placed in the HTML \f[CB]<title>\f[R] tag.
1161 The text specified in the \f[CB]title\f[R] tag appears in the window title
1162 and in any browser bookmarks (favorite places) that someone creates for
1163 this page.
1164 This title shouldn\[aq]t contain any HTML tags because the browser
1165 doesn\[aq]t interpret them correctly.
1166 Use escape characters on any internal quotation marks within the
1167 \f[CB]title\f[R] tag.
1168 If the \f[CB]\-windowtitle\f[R] option is omitted, then the
1169 \f[CB]javadoc\f[R] tool uses the value of the \f[CB]\-doctitle\f[R] option
1170 for the \f[CB]\-windowtitle\f[R] option.
1171 For example,
1172 \f[CB]javadoc\ \-windowtitle\ "My\ Library"\ com.mypackage\f[R].
1173 .RS
1174 .RE
1176 .PP
1177 The following are additional options provided by the standard doclet and
1178 are subject to change without notice.
1179 Additional options might are less commonly used or are otherwise
1180 regarded as advanced.
1181 .TP
1182 .B \f[CB]\-Xdoclint\f[R]
1183 Enables recommended checks for problems in Javadoc comments.
1184 .RS
1185 .RE
1186 .TP
1187 .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])
1188 Enable or disable specific checks for bad references, lack of
1189 accessibility, missing Javadoc comments, and reports errors for invalid
1190 Javadoc syntax and missing HTML tags.
1191 .RS
1192 .PP
1193 This option enables the \f[CB]javadoc\f[R] tool to check for all
1194 documentation comments included in the generated output.
1195 You can select which items to include in the generated output with the
1196 standard options \f[CB]\-public\f[R], \f[CB]\-protected\f[R],
1197 \f[CB]\-package\f[R] and \f[CB]\-private\f[R].
1198 .PP
1199 When the \f[CB]\-Xdoclint\f[R] is enabled, it reports issues with messages
1200 similar to the \f[CB]javac\f[R] command.
1201 The \f[CB]javadoc\f[R] tool prints a message, a copy of the source line,
1202 and a caret pointing at the exact position where the error was detected.
1203 Messages may be either warnings or errors, depending on their severity
1204 and the likelihood to cause an error if the generated documentation were
1205 run through a validator.
1206 For example, bad references or missing Javadoc comments don\[aq]t cause
1207 the \f[CB]javadoc\f[R] tool to generate invalid HTML, so these issues are
1208 reported as warnings.
1209 Syntax errors or missing HTML end tags cause the \f[CB]javadoc\f[R] tool
1210 to generate invalid output, so these issues are reported as errors.
1211 .PP
1212 \f[CB]\-Xdoclint\f[R] option validates input comments based upon the
1213 requested markup.
1214 .PP
1215 By default, the \f[CB]\-Xdoclint\f[R] option is enabled.
1216 Disable it with the option \f[CB]\-Xdoclint:none\f[R].
1217 .PP
1218 The following options change what the \f[CB]\-Xdoclint\f[R] option
1219 reports:
1220 .IP \[bu] 2
1221 \f[CB]\-Xdoclint\ none\f[R]: Disables the \f[CB]\-Xdoclint\f[R] option
1222 .IP \[bu] 2
1223 \f[CB]\-Xdoclint\f[R] \f[I]group\f[R]: Enables \f[I]group\f[R] checks
1224 .IP \[bu] 2
1225 \f[CB]\-Xdoclint\ all\f[R]: Enables all groups of checks
1226 .IP \[bu] 2
1227 \f[CB]\-Xdoclint\ all,\-\f[R]\f[I]group\f[R]: Enables all checks except
1228 \f[I]group\f[R] checks
1229 .PP
1230 The \f[I]group\f[R] variable has one of the following values:
1231 .IP \[bu] 2
1232 \f[CB]accessibility\f[R]: Checks for the issues to be detected by an
1233 accessibility checker (for example, no caption or summary attributes
1234 specified in a \f[CB]<table>\f[R] tag).
1235 .IP \[bu] 2
1236 \f[CB]html\f[R]: Detects high\-level HTML issues, such as putting block
1237 elements inside inline elements, or not closing elements that require an
1238 end tag.
1239 The rules are derived from the \f[B]HTML 4 Specification\f[R]
1240 [https://www.w3.org/TR/html4/] or the \f[B]HTML 5 Specification\f[R]
1241 [http://www.w3.org/TR/2014/REC\-html5\-20141028/] based on the standard
1242 doclet \f[CB]html\f[R] output generation selected.
1243 This type of check enables the \f[CB]javadoc\f[R] tool to detect HTML
1244 issues that some browsers might not interpret as intended.
1245 .IP \[bu] 2
1246 \f[CB]missing\f[R]: Checks for missing Javadoc comments or tags (for
1247 example, a missing comment or class, or a missing \f[CB]\@return\f[R] tag
1248 or similar tag on a method).
1249 .IP \[bu] 2
1250 \f[CB]reference\f[R]: Checks for issues relating to the references to Java
1251 API elements from Javadoc tags (for example, item not found in
1252 \f[CB]\@see\f[R], or a bad name after \f[CB]\@param)\f[R].
1253 .IP \[bu] 2
1254 \f[CB]syntax\f[R]: Checks for low level issues like unescaped angle
1255 brackets (\f[CB]<\f[R] and \f[CB]>\f[R]) and ampersands (\f[CB]&\f[R]) and
1256 invalid Javadoc tags.
1257 .PP
1258 You can specify the \f[CB]\-Xdoclint\f[R] option multiple times to enable
1259 the option to check errors and warnings in multiple categories.
1260 Alternatively, you can specify multiple error and warning categories by
1261 using the preceding options.
1262 For example, use either of the following commands to check for the HTML,
1263 syntax, and accessibility issues in the file \f[I]filename\f[R].
1264 .RS
1265 .PP
1266 \f[CB]javadoc\ \-Xdoclint:html\ \-Xdoclint:syntax\ \-Xdoclint:accessibility\f[R]
1267 \f[I]filename\f[R]
1268 .RE
1269 .RS
1270 .PP
1271 \f[CB]javadoc\ \-Xdoclint:html,syntax,accessibility\f[R] \f[I]filename\f[R]
1272 .RE
1273 .PP
1274 \f[B]Note:\f[R]
1275 .PP
1276 The \f[CB]javadoc\f[R] tool doesn\[aq]t guarantee the completeness of
1277 these checks.
1278 In particular, it isn\[aq]t a full HTML compliance checker.
1279 The goal of the \-\f[CB]Xdoclint\f[R] option is to enable the
1280 \f[CB]javadoc\f[R] tool to report majority of common errors.
1281 .PP
1282 The \f[CB]javadoc\f[R] tool doesn\[aq]t attempt to fix invalid input, it
1283 just reports it.
1284 .RE
1285 .TP
1286 .B \f[CB]\-Xdoclint/package:\f[R][\f[CB]\-\f[R]]\f[I]packages\f[R]
1287 Enables or disables checks in specific packages.
1288 \f[I]packages\f[R] is a comma separated list of package specifiers.
1289 A package specifier is either a qualified name of a package or a package
1290 name prefix followed by \f[CB]*\f[R], which expands to all sub packages of
1291 the given package.
1292 Prefix the package specifier with \f[CB]\-\f[R] to disable checks for the
1293 specified packages.
1294 .RS
1295 .RE
1296 .TP
1297 .B \f[CB]\-Xdocrootparent\f[R] \f[I]url\f[R]
1298 Replaces all \f[CB]\@docRoot\f[R] items followed by\f[CB]/..\f[R] in Javadoc
1299 comments with the \f[I]url\f[R].
1300 .RS
1301 .RE