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