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