jdk

1
.\" Copyright (c) 1994, 2024, 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.19.2
23
.\"
24
.\" Define V font for inline verbatim, using C font in formats
25
.\" that render this, and otherwise B font.
26
.ie "\f[CB]x\f[R]"x" \{\
27
. ftr V B
28
. ftr VI BI
29
. ftr VB B
30
. ftr VBI BI
31
.\}
32
.el \{\
33
. ftr V CR
34
. ftr VI CI
35
. ftr VB CB
36
. ftr VBI CBI
37
.\}
38
.TH "JAVADOC" "1" "2025" "JDK 24-ea" "JDK Commands"
39
.hy
40
.SH NAME
41
.PP
42
javadoc - generate HTML pages of API documentation from Java source
43
files
44
.SH SYNOPSIS
45
.PP
46
\f[V]javadoc\f[R] [\f[I]options\f[R]] [\f[I]packagenames\f[R]]
47
[\f[I]sourcefiles\f[R]] [\f[V]\[at]\f[R]\f[I]files\f[R]]
48
.TP
49
\f[I]options\f[R]
50
Specifies command-line options, separated by spaces.
51
See \f[B]Standard \f[VB]javadoc\f[B] Options\f[R], \f[B]Extra
52
\f[VB]javadoc\f[B] Options\f[R], \f[B]Standard Options for the Standard
53
Doclet\f[R], and \f[B]Extra Options for the Standard Doclet\f[R].
54
.TP
55
\f[I]packagenames\f[R]
56
Specifies names of packages that you want to document, separated by
57
spaces, for example \f[V]java.lang java.lang.reflect java.awt\f[R].
58
If you want to also document the subpackages, then use the
59
\f[V]-subpackages\f[R] option to specify the packages.
60
.RS
61
.PP
62
By default, \f[V]javadoc\f[R] looks for the specified packages in the
63
current directory and subdirectories.
64
Use the \f[V]-sourcepath\f[R] option to specify the list of directories
65
where to look for packages.
66
.RE
67
.TP
68
\f[I]sourcefiles\f[R]
69
Specifies names of Java source files that you want to document,
70
separated by spaces, for example
71
\f[V]Class.java Object.java Button.java\f[R].
72
By default, \f[V]javadoc\f[R] looks for the specified classes in the
73
current directory.
74
However, you can specify the full path to the class file and use
75
wildcard characters, for example
76
\f[V]/home/src/java/awt/Graphics*.java\f[R].
77
You can also specify the path relative to the current directory.
78
.TP
79
\f[V]\[at]\f[R]\f[I]files\f[R]
80
Specifies names of files that contain a list of \f[V]javadoc\f[R] tool
81
options, package names, and source file names in any order.
82
.SH DESCRIPTION
83
.PP
84
The \f[V]javadoc\f[R] tool parses the declarations and documentation
85
comments in a set of Java source files and produces corresponding HTML
86
pages that describe (by default) the public and protected classes,
87
nested and implicitly declared classes (but not anonymous inner
88
classes), interfaces, constructors, methods, and fields.
89
You can use the \f[V]javadoc\f[R] tool to generate the API documentation
90
or the implementation documentation for a set of source files.
91
.PP
92
You can run the \f[V]javadoc\f[R] tool on entire packages, individual
93
source files, or both.
94
When documenting entire packages, you can use the \f[V]-subpackages\f[R]
95
option either to recursively traverse a directory and its
96
subdirectories, or to pass in an explicit list of package names.
97
When you document individual source files, pass in a list of Java source
98
file names.
99
.SS Documentation Comments
100
.PP
101
The \f[V]javadoc\f[R] tool uses the documentation comment, if any, that
102
immediately precedes the beginning of the declaration, whether that is
103
an annotation, modifier, or the name being declared.
104
If there are multiple documentation comments before the declaration,
105
only the last one (closest to the declaration) will be used.
106
If there are any documentation comments after the beginning of the
107
declaration, they will be ignored.
108
To check for any extra or misplaced documentation comments, compile your
109
source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more
110
specifically, \f[V]-Xlint:dangling-doc-comments\f[R].
111
Within a source file, you may suppress any warnings generated by these
112
options by using
113
\f[V]\[at]SuppressWarnings(\[dq]dangling-doc-comments\[dq])\f[R] on a
114
suitable enclosing declaration.
115
.SS Conformance
116
.PP
117
The standard doclet does not validate the content of documentation
118
comments for conformance, nor does it attempt to correct any errors in
119
documentation comments.
120
Anyone running javadoc is advised to be aware of the problems that may
121
arise when generating non-conformant output or output containing
122
executable content, such as JavaScript.
123
The standard doclet does provide the \f[B]DocLint\f[R] feature to help
124
developers detect common problems in documentation comments; but it is
125
also recommended to check the generated output with any appropriate
126
conformance and other checking tools.
127
.PP
128
For more details on the conformance requirements for HTML5 documents,
129
see \f[B]Conformance requirements for authors\f[R]
130
[https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors]
131
in the HTML5 Specification.
132
For more details on security issues related to web pages, see the
133
\f[B]Open Web Application Security Project (OWASP)\f[R]
134
[https://www.owasp.org] page.
135
.SH OPTIONS
136
.PP
137
\f[V]javadoc\f[R] supports command-line options for both the main
138
\f[V]javadoc\f[R] tool and the currently selected doclet.
139
The standard doclet is used if no other doclet is specified.
140
.PP
141
GNU-style options (that is, those beginning with \f[V]--\f[R]) can use
142
an equal sign (\f[V]=\f[R]) instead of whitespace characters to separate
143
the name of an option from its value.
144
.SS Standard \f[V]javadoc\f[R] Options
145
.PP
146
The following core \f[V]javadoc\f[R] options are equivalent to
147
corresponding \f[V]javac\f[R] options.
148
See \f[I]Standard Options\f[R] in \f[B]javac\f[R] for the detailed
149
descriptions of using these options:
150
.IP \[bu] 2
151
\f[V]--add-modules\f[R]
152
.IP \[bu] 2
153
\f[V]-bootclasspath\f[R]
154
.IP \[bu] 2
155
\f[V]--class-path\f[R], \f[V]-classpath\f[R], or \f[V]-cp\f[R]
156
.IP \[bu] 2
157
\f[V]--disable-line-doc-comments\f[R]
158
.IP \[bu] 2
159
\f[V]--enable-preview\f[R]
160
.IP \[bu] 2
161
\f[V]-encoding\f[R]
162
.IP \[bu] 2
163
\f[V]-extdirs\f[R]
164
.IP \[bu] 2
165
\f[V]--limit-modules\f[R]
166
.IP \[bu] 2
167
\f[V]--module\f[R]
168
.IP \[bu] 2
169
\f[V]--module-path\f[R] or \f[V]-p\f[R]
170
.IP \[bu] 2
171
\f[V]--module-source-path\f[R]
172
.IP \[bu] 2
173
\f[V]--release\f[R]
174
.IP \[bu] 2
175
\f[V]--source\f[R] or \f[V]-source\f[R]
176
.IP \[bu] 2
177
\f[V]--source-path\f[R] or \f[V]-sourcepath\f[R]
178
.IP \[bu] 2
179
\f[V]--system\f[R]
180
.IP \[bu] 2
181
\f[V]--upgrade-module-path\f[R]
182
.PP
183
The following options are the core \f[V]javadoc\f[R] options that are
184
not equivalent to a corresponding \f[V]javac\f[R] option:
185
.TP
186
\f[V]-breakiterator\f[R]
187
Computes the first sentence of the description in a documentation
188
comment using an instance of \f[V]java.text.BreakIterator\f[R] to detect
189
\f[I]sentence breaks\f[R].
190
The rules that are used depend on the \f[B]current locale\f[R]: for
191
example, for English, a sentence break occurs after a period, question
192
mark, or exclamation point followed by a space when the next word starts
193
with a capital letter.
194
(This is meant to handle most abbreviations, such as \[dq]The serial no.
195
is valid\[dq], but will not handle \[dq]Mr.
196
Smith\[dq].)
197
.RS
198
.PP
199
The option is enabled by default if the language of the current locale
200
is not English.
201
If the language of the current locale is English, and the
202
\f[V]-breakiterator\f[R] option is not given, a simple default algorithm
203
is used, which just looks for a period followed by a space.
204
.PP
205
In a traditional \f[V]/**...*/\f[R] comment, the search for the end of
206
the first sentence is terminated by an HTML block tag, such as
207
\f[V]<p>\f[R], \f[V]<pre>\f[R], or the tag for a heading.
208
.PP
209
In a Markdown \f[V]///\f[R] comment, the search for the end of the first
210
sentence skips over any characters enclosed in code spans and links, and
211
is terminated by the end of the initial block, as indicated by a blank
212
line or the beginning of the next block, such as a list, thematic break,
213
or an HTML block.
214
.PP
215
The first sentence of the description in a documentation comment is used
216
in summary tables, index pages, and other situations where a short
217
summary is required.
218
For more explicit control in any individual documentation comment,
219
enclose the contents of the first sentence in a
220
\f[V]{\[at]summary ...}\f[R] tag, or when applicable, in a
221
\f[V]{\[at]return ...}\f[R] tag.
222
.RE
223
.TP
224
\f[V]-doclet\f[R] \f[I]class\f[R]
225
Generates output by using an alternate doclet.
226
Use the fully qualified name.
227
This doclet defines the content and formats the output.
228
If the \f[V]-doclet\f[R] option isn\[aq]t used, then the
229
\f[V]javadoc\f[R] tool uses the standard doclet for generating the
230
default HTML format.
231
This class must implement the \f[V]jdk.javadoc.doclet.Doclet\f[R]
232
interface.
233
The path to this class is defined by the \f[V]-docletpath\f[R] option.
234
.TP
235
\f[V]-docletpath\f[R] \f[I]path\f[R]
236
Specifies where to find doclet class files (specified with the
237
\f[V]-doclet\f[R] option) and any JAR files it depends on.
238
If the starting class file is in a JAR file, then this option specifies
239
the path to that JAR file.
240
You can specify an absolute path or a path relative to the current
241
directory.
242
If \f[V]path\f[R] contains multiple paths or JAR files, then they should
243
be separated with a colon (\f[V]:\f[R]) on Linux and macOS, and a
244
semicolon (\f[V];\f[R]) on Windows.
245
This option isn\[aq]t necessary when the \f[V]doclet\f[R] starting class
246
is already in the search path.
247
.TP
248
\f[V]-exclude\f[R] \f[I]pkglist\f[R]
249
Unconditionally, excludes the specified packages and their subpackages
250
from the list formed by \f[V]-subpackages\f[R].
251
It excludes those packages even when they would otherwise be included by
252
some earlier or later \f[V]-subpackages\f[R] option.
253
.RS
254
.PP
255
The following example would include \f[V]java.io\f[R],
256
\f[V]java.util\f[R], and \f[V]java.math\f[R] (among others), but would
257
exclude packages rooted at \f[V]java.net\f[R] and \f[V]java.lang\f[R].
258
Notice that these examples exclude \f[V]java.lang.ref\f[R], which is a
259
subpackage of \f[V]java.lang\f[R].
260
Arguments are separated by colons on all operating systems.
261
.IP \[bu] 2
262
\f[B]Linux and macOS:\f[R]
263
.RS 2
264
.IP
265
.nf
266
\f[CB]
267
javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
268
\f[R]
269
.fi
270
.RE
271
.IP \[bu] 2
272
\f[B]Windows:\f[R]
273
.RS 2
274
.IP
275
.nf
276
\f[CB]
277
javadoc -sourcepath \[rs]user\[rs]src -subpackages java -exclude java.net:java.lang
278
\f[R]
279
.fi
280
.RE
281
.RE
282
.TP
283
\f[V]--expand-requires\f[R] (\f[V]transitive\f[R]|\f[V]all\f[R])
284
Instructs the javadoc tool to expand the set of modules to be
285
documented.
286
By default, only the modules given explicitly on the command line are
287
documented.
288
Supports the following values:
289
.RS
290
.IP \[bu] 2
291
\f[V]transitive\f[R]: additionally includes all the required transitive
292
dependencies of those modules.
293
.IP \[bu] 2
294
\f[V]all\f[R]: includes all dependencies.
295
.RE
296
.TP
297
\f[V]--help\f[R], \f[V]-help\f[R], \f[V]-h\f[R], or \f[V]-?\f[R]
298
Prints a synopsis of the standard options.
299
.TP
300
\f[V]--help-extra\f[R] or \f[V]-X\f[R]
301
Prints a synopsis of the set of extra options.
302
.TP
303
\f[V]-J\f[R]\f[I]flag\f[R]
304
Passes \f[I]flag\f[R] directly to the Java Runtime Environment (JRE)
305
that runs the \f[V]javadoc\f[R] tool.
306
For example, if you must ensure that the system sets aside 32 MB of
307
memory in which to process the generated documentation, then you would
308
call the \f[V]-Xmx\f[R] option as follows:
309
\f[V]javadoc -J-Xmx32m -J-Xms32m com.mypackage\f[R].
310
Be aware that \f[V]-Xms\f[R] is optional because it only sets the size
311
of initial memory, which is useful when you know the minimum amount of
312
memory required.
313
.RS
314
.PP
315
There is no space between the \f[V]J\f[R] and the \f[V]flag\f[R].
316
.PP
317
Use the \f[V]-version\f[R] option to report the version of the JRE being
318
used to run the \f[V]javadoc\f[R] tool.
319
.IP
320
.nf
321
\f[CB]
322
javadoc -J-version
323
java version \[dq]17\[dq] 2021-09-14 LTS
324
Java(TM) SE Runtime Environment (build 17+35-LTS-2724)
325
Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)
326
\f[R]
327
.fi
328
.RE
329
.TP
330
\f[V]-locale\f[R] \f[I]name\f[R]
331
Specifies the locale that the \f[V]javadoc\f[R] tool uses when it
332
generates documentation.
333
The argument is the name of the locale, as described in
334
\f[V]java.util.Locale\f[R] documentation, such as \f[V]en_US\f[R]
335
(English, United States) or \f[V]en_US_WIN\f[R] (Windows variant).
336
.RS
337
.PP
338
Specifying a locale causes the \f[V]javadoc\f[R] tool to choose the
339
resource files of that locale for messages such as strings in the
340
navigation bar, headings for lists and tables, help file contents,
341
comments in the \f[V]stylesheet.css\f[R] file, and so on.
342
It also specifies the sorting order for lists sorted alphabetically, and
343
the sentence separator to determine the end of the first sentence.
344
The \f[V]-locale\f[R] option doesn\[aq]t determine the locale of the
345
documentation comment text specified in the source files of the
346
documented classes.
347
.RE
348
.TP
349
\f[V]-package\f[R]
350
Shows only package, protected, and public classes and members.
351
.TP
352
\f[V]-private\f[R]
353
Shows all classes and members.
354
.TP
355
\f[V]-protected\f[R]
356
Shows only protected and public classes and members.
357
This is the default.
358
.TP
359
\f[V]-public\f[R]
360
Shows only the public classes and members.
361
.TP
362
\f[V]-quiet\f[R]
363
Shuts off messages so that only the warnings and errors appear to make
364
them easier to view.
365
It also suppresses the \f[V]version\f[R] string.
366
.TP
367
\f[V]--show-members\f[R] \f[I]value\f[R]
368
Specifies which members (fields, methods, or constructors) are
369
documented, where \f[I]value\f[R] can be any of the following:
370
.RS
371
.IP \[bu] 2
372
\f[V]public\f[R] --- shows only public members
373
.IP \[bu] 2
374
\f[V]protected\f[R] --- shows public and protected members; this is the
375
default
376
.IP \[bu] 2
377
\f[V]package\f[R] --- shows public, protected, and package members
378
.IP \[bu] 2
379
\f[V]private\f[R] --- shows all members
380
.RE
381
.TP
382
\f[V]--show-module-contents\f[R] \f[I]value\f[R]
383
Specifies the documentation granularity of module declarations, where
384
\f[I]value\f[R] can be \f[V]api\f[R] or \f[V]all\f[R].
385
.TP
386
\f[V]--show-packages\f[R] \f[I]value\f[R]
387
Specifies which module packages are documented, where \f[I]value\f[R]
388
can be \f[V]exported\f[R] or \f[V]all\f[R] packages.
389
.TP
390
\f[V]--show-types\f[R] \f[I]value\f[R]
391
Specifies which types (classes, interfaces, etc.)
392
are documented, where \f[I]value\f[R] can be any of the following:
393
.RS
394
.IP \[bu] 2
395
\f[V]public\f[R] --- shows only public types
396
.IP \[bu] 2
397
\f[V]protected\f[R] --- shows public and protected types; this is the
398
default
399
.IP \[bu] 2
400
\f[V]package\f[R] --- shows public, protected, and package types
401
.IP \[bu] 2
402
\f[V]private\f[R] --- shows all types
403
.RE
404
.TP
405
\f[V]-subpackages\f[R] \f[I]subpkglist\f[R]
406
Generates documentation from source files in the specified packages and
407
recursively in their subpackages.
408
This option is useful when adding new subpackages to the source code
409
because they are automatically included.
410
Each package argument is any top-level subpackage (such as
411
\f[V]java\f[R]) or fully qualified package (such as
412
\f[V]javax.swing\f[R]) that doesn\[aq]t need to contain source files.
413
Arguments are separated by colons on all operating systems.
414
Wild cards aren\[aq]t allowed.
415
Use \f[V]-sourcepath\f[R] to specify where to find the packages.
416
This option doesn\[aq]t process source files that are in the source tree
417
but don\[aq]t belong to the packages.
418
.RS
419
.PP
420
For example, the following commands generates documentation for packages
421
named \f[V]java\f[R] and \f[V]javax.swing\f[R] and all of their
422
subpackages.
423
.IP \[bu] 2
424
\f[B]Linux and macOS:\f[R]
425
.RS 2
426
.IP
427
.nf
428
\f[CB]
429
javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
430
\f[R]
431
.fi
432
.RE
433
.IP \[bu] 2
434
\f[B]Windows:\f[R]
435
.RS 2
436
.IP
437
.nf
438
\f[CB]
439
javadoc -d docs -sourcepath \[rs]user\[rs]src -subpackages java:javax.swing
440
\f[R]
441
.fi
442
.RE
443
.RE
444
.TP
445
\f[V]-verbose\f[R]
446
Provides more detailed messages while the \f[V]javadoc\f[R] tool runs.
447
Without the \f[V]-verbose\f[R] option, messages appear for loading the
448
source files, generating the documentation (one message per source
449
file), and sorting.
450
The \f[V]-verbose\f[R] option causes the printing of additional messages
451
that specify the number of milliseconds to parse each Java source file.
452
.TP
453
\f[V]--version\f[R]
454
Prints version information.
455
.TP
456
\f[V]-Werror\f[R]
457
Reports an error if any warnings occur.
458
.PP
459
Note that if a Java source file contains an implicitly declared class,
460
then that class and its public, protected, and package members will be
461
documented regardless of the options such as \f[V]--show-types\f[R],
462
\f[V]--show-members\f[R], \f[V]-private\f[R], \f[V]-protected\f[R],
463
\f[V]-package\f[R], and \f[V]-public\f[R].
464
If \f[V]--show-members\f[R] is specified with value \f[V]private\f[R] or
465
if \f[V]-private\f[R] is used then all private members of an implicitly
466
declared class will be documented too.
467
.SS Extra \f[V]javadoc\f[R] Options
468
.PP
469
\f[I]Note:\f[R] The additional options for \f[V]javadoc\f[R] are subject
470
to change without notice.
471
.PP
472
The following additional \f[V]javadoc\f[R] options are equivalent to
473
corresponding \f[V]javac\f[R] options.
474
See \f[I]Extra Options\f[R] in \f[B]javac\f[R] for the detailed
475
descriptions of using these options:
476
.IP \[bu] 2
477
\f[V]--add-exports\f[R]
478
.IP \[bu] 2
479
\f[V]--add-reads\f[R]
480
.IP \[bu] 2
481
\f[V]--patch-module\f[R]
482
.IP \[bu] 2
483
\f[V]-Xmaxerrs\f[R]
484
.IP \[bu] 2
485
\f[V]-Xmaxwarns\f[R]
486
.SS Standard Options for the Standard Doclet
487
.PP
488
The following options are provided by the standard doclet.
489
.TP
490
\f[V]--add-script\f[R] \f[I]file\f[R]
491
Adds \f[I]file\f[R] as an additional JavaScript file to the generated
492
documentation.
493
This option can be used one or more times to specify additional script
494
files.
495
.RS
496
.PP
497
Command-line example:
498
.RS
499
.PP
500
\f[V]javadoc --add-script first_script.js --add-script second_script.js pkg_foo\f[R]
501
.RE
502
.RE
503
.TP
504
\f[V]--add-stylesheet\f[R] \f[I]file\f[R]
505
Adds \f[I]file\f[R] as an additional stylesheet file to the generated
506
documentation.
507
This option can be used one or more times to specify additional
508
stylesheets included in the documentation.
509
.RS
510
.PP
511
Command-line example:
512
.IP
513
.nf
514
\f[CB]
515
javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo
516
\f[R]
517
.fi
518
.RE
519
.TP
520
\f[V]--allow-script-in-comments\f[R]
521
Allow JavaScript in documentation comments, and options whose value is
522
\f[I]html-code\f[R].
523
.TP
524
\f[V]-author\f[R]
525
Includes the text of any \f[V]author\f[R] tags in the generated
526
documentation.
527
.TP
528
\f[V]-bottom\f[R] \f[I]html-code\f[R]
529
Specifies the text to be placed at the bottom of each generated page.
530
The text can contain HTML tags and white space, but when it does, the
531
text must be enclosed in quotation marks.
532
Use escape characters for any internal quotation marks within text.
533
.TP
534
\f[V]-charset\f[R] \f[I]name\f[R]
535
Specifies the HTML character set for this document.
536
The name should be a preferred MIME name as specified in the \f[B]IANA
537
Registry, Character Sets\f[R]
538
[http://www.iana.org/assignments/character-sets].
539
.RS
540
.PP
541
For example:
542
.IP
543
.nf
544
\f[CB]
545
javadoc -charset \[dq]iso-8859-1\[dq] mypackage
546
\f[R]
547
.fi
548
.PP
549
This command inserts the following line, containing a
550
\f[B]\f[VB]meta\f[B] element\f[R]
551
[https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element]
552
in the head of every generated page:
553
.IP
554
.nf
555
\f[CB]
556
<meta http-equiv=\[dq]Content-Type\[dq] content=\[dq]text/html; charset=ISO-8859-1\[dq]>
557
\f[R]
558
.fi
559
.RE
560
.TP
561
\f[V]-d\f[R] \f[I]directory\f[R]
562
Specifies the destination directory where the \f[V]javadoc\f[R] tool
563
saves the generated HTML files.
564
If you omit the \f[V]-d\f[R] option, then the files are saved to the
565
current directory.
566
The \f[V]directory\f[R] value can be absolute or relative to the current
567
working directory.
568
The destination directory is automatically created when the
569
\f[V]javadoc\f[R] tool runs.
570
.RS
571
.IP \[bu] 2
572
\f[B]Linux and macOS:\f[R] For example, the following command generates
573
the documentation for the package \f[V]com.mypackage\f[R] and saves the
574
results in the \f[V]/user/doc/\f[R] directory:
575
.RS 2
576
.IP
577
.nf
578
\f[CB]
579
javadoc -d /user/doc/ com.mypackage
580
\f[R]
581
.fi
582
.RE
583
.IP \[bu] 2
584
\f[B]Windows:\f[R] For example, the following command generates the
585
documentation for the package \f[V]com.mypackage\f[R] and saves the
586
results in the \f[V]\[rs]user\[rs]doc\[rs]\f[R] directory:
587
.RS 2
588
.IP
589
.nf
590
\f[CB]
591
javadoc -d \[rs]user\[rs]doc\[rs] com.mypackage
592
\f[R]
593
.fi
594
.RE
595
.RE
596
.TP
597
\f[V]-docencoding\f[R] \f[I]name\f[R]
598
Specifies the encoding of the generated HTML files.
599
The name should be a preferred MIME name as specified in the \f[B]IANA
600
Registry, Character Sets\f[R]
601
[http://www.iana.org/assignments/character-sets].
602
.RS
603
.PP
604
Three options are available for use in a \f[V]javadoc\f[R] encoding
605
command.
606
The \f[V]-encoding\f[R] option is used for encoding the files read by
607
the \f[V]javadoc\f[R] tool, while the \f[V]-docencoding\f[R] and
608
\f[V]-charset\f[R] options are used for encoding the files written by
609
the tool.
610
Of the three available options, at most, only the input and an output
611
encoding option are used in a single encoding command.
612
If you specify both input and output encoding options in a command, they
613
must be the same value.
614
If you specify neither output option, it defaults to the input encoding.
615
.PP
616
For example:
617
.IP
618
.nf
619
\f[CB]
620
javadoc -docencoding \[dq]iso-8859-1\[dq] mypackage
621
\f[R]
622
.fi
623
.RE
624
.TP
625
\f[V]-docfilessubdirs\f[R]
626
Enables deep copying of \f[V]doc-files\f[R] directories.
627
Subdirectories and all contents are recursively copied to the
628
destination.
629
For example, the directory \f[V]doc-files/example/images\f[R] and all of
630
its contents are copied.
631
Use the \f[B]\f[VB]-excludedocfilessubdir\f[B]\f[R] option to restrict
632
the subdirectories to be copied.
633
.TP
634
\f[V]-doctitle\f[R] \f[I]html-code\f[R]
635
Specifies the title to place near the top of the overview summary file.
636
The text specified in the \f[V]title\f[R] tag is placed as a centered,
637
level-one heading directly beneath the navigation bar.
638
The \f[V]title\f[R] tag can contain HTML tags and white space, but when
639
it does, you must enclose the title in quotation marks.
640
Additional quotation marks within the \f[V]title\f[R] tag must be
641
escaped.
642
For example,
643
\f[V]javadoc -doctitle \[dq]<b>My Library</b><br>v1.0\[dq] com.mypackage\f[R].
644
.TP
645
\f[V]-excludedocfilessubdir\f[R] \f[I]name1\f[R]\f[V],\f[R]\f[I]name2...\f[R]
646
Excludes any subdirectories with the given names when recursively
647
copying \f[V]doc-files\f[R] subdirectories.
648
See \f[B]\f[VB]-docfilessubdirs\f[B]\f[R].
649
For historical reasons, \f[V]:\f[R] can be used anywhere in the argument
650
as a separator instead of \f[V],\f[R].
651
.TP
652
\f[V]-footer\f[R] \f[I]html-code\f[R]
653
This option is no longer supported and reports a warning.
654
.TP
655
\f[V]-group\f[R] \f[I]name\f[R] \f[I]p1\f[R]\f[V],\f[R]\f[I]p2...\f[R]
656
Group the specified packages together in the Overview page.
657
For historical reasons, \f[V]:\f[R] can be used as a separator anywhere
658
in the argument instead of \f[V],\f[R].
659
.TP
660
\f[V]-header\f[R] \f[I]html-code\f[R]
661
Specifies the header text to be placed at the top of each output file.
662
The header is placed to the right of the navigation bar.
663
The \f[V]header\f[R] can contain HTML tags and white space, but when it
664
does, the \f[V]header\f[R] must be enclosed in quotation marks.
665
Use escape characters for internal quotation marks within a header.
666
For example,
667
\f[V]javadoc -header \[dq]<b>My Library</b><br>v1.0\[dq] com.mypackage\f[R].
668
.TP
669
\f[V]-helpfile\f[R] \f[I]filename\f[R]
670
Specifies a file containing the text that will be displayed when the
671
\f[B]HELP\f[R] link in the navigation bar is clicked.
672
If this option is not given, the \f[V]javadoc\f[R] tool creates a
673
default page that will be used.
674
.TP
675
\f[V]-html5\f[R]
676
This option is a no-op and is just retained for backwards compatibility.
677
.TP
678
\f[V]--javafx\f[R] or \f[V]-javafx\f[R]
679
Enables JavaFX functionality.
680
This option is enabled by default if the JavaFX library classes are
681
detected on the module path.
682
.TP
683
\f[V]-keywords\f[R]
684
Adds HTML keyword \f[V]<meta>\f[R] tags to the generated file for each
685
class.
686
These tags can help search engines that look for \f[V]<meta>\f[R] tags
687
find the pages.
688
Most search engines that search the entire Internet don\[aq]t look at
689
\f[V]<meta>\f[R] tags, because pages can misuse them.
690
Search engines offered by companies that confine their searches to their
691
own website can benefit by looking at \f[V]<meta>\f[R] tags.
692
The \f[V]<meta>\f[R] tags include the fully qualified name of the class
693
and the unqualified names of the fields and methods.
694
Constructors aren\[aq]t included because they are identical to the class
695
name.
696
For example, the page for the class \f[V]String\f[R] includes these
697
keywords:
698
.RS
699
.IP
700
.nf
701
\f[CB]
702
<meta name=\[dq]keywords\[dq] content=\[dq]java.lang.String class\[dq]>
703
<meta name=\[dq]keywords\[dq] content=\[dq]CASE_INSENSITIVE_ORDER\[dq]>
704
<meta name=\[dq]keywords\[dq] content=\[dq]length()\[dq]>
705
<meta name=\[dq]keywords\[dq] content=\[dq]isEmpty()\[dq]>
706
\f[R]
707
.fi
708
.RE
709
.TP
710
\f[V]-link\f[R] \f[I]url\f[R]
711
Creates links to existing \f[V]javadoc\f[R] generated documentation of
712
externally referenced classes.
713
The \f[I]url\f[R] argument is the absolute or relative URL of the
714
directory that contains the external \f[V]javadoc\f[R] generated
715
documentation.
716
You can specify multiple \f[V]-link\f[R] options in a specified
717
\f[V]javadoc\f[R] tool run to link to multiple documents.
718
.RS
719
.PP
720
Either a \f[V]package-list\f[R] or an \f[V]element-list\f[R] file must
721
be in this \f[I]url\f[R] directory (otherwise, use the
722
\f[V]-linkoffline\f[R] option).
723
.PP
724
\f[I]Note:\f[R] The \f[V]package-list\f[R] and \f[V]element-list\f[R]
725
files are generated by the \f[V]javadoc\f[R] tool when generating the
726
API documentation and should not be modified by the user.
727
.PP
728
When you use the \f[V]javadoc\f[R] tool to document packages, it uses
729
the \f[V]package-list\f[R] file to determine the packages declared in an
730
API.
731
When you generate API documents for modules, the \f[V]javadoc\f[R] tool
732
uses the \f[V]element-list\f[R] file to determine the modules and
733
packages declared in an API.
734
.PP
735
The \f[V]javadoc\f[R] tool reads the names from the appropriate list
736
file and then links to the packages or modules at that URL.
737
.PP
738
When the \f[V]javadoc\f[R] tool runs, the \f[I]url\f[R] value is copied
739
into the \f[V]<a href>\f[R] links that are created.
740
Therefore, \f[I]url\f[R] must be the URL to the directory and not to a
741
file.
742
.PP
743
You can use an absolute link for \f[I]url\f[R] to enable your documents
744
to link to a document on any web site, or you can use a relative link to
745
link only to a relative location.
746
If you use a relative link, then the value you pass in should be the
747
relative path from the destination directory (specified with the
748
\f[V]-d\f[R] option) to the directory containing the packages being
749
linked to.
750
When you specify an absolute link, you usually use an HTTP link.
751
However, if you want to link to a file system that has no web server,
752
then you can use a file link.
753
Use a file link only when everyone who wants to access the generated
754
documentation shares the same file system.
755
In all cases, and on all operating systems, use a slash as the
756
separator, whether the URL is absolute or relative, and
757
\f[V]https:\f[R], \f[V]http:\f[R], or \f[V]file:\f[R] as specified in
758
the \f[B]RFC 1738: Uniform Resource Locators (URL)\f[R]
759
[https://www.rfc-editor.org/info/rfc1738].
760
.IP
761
.nf
762
\f[CB]
763
-link https://<host>/<directory>/<directory>/.../<name>
764
-link http://<host>/<directory>/<directory>/.../<name>
765
-link file://<host>/<directory>/<directory>/.../<name>
766
-link <directory>/<directory>/.../<name>
767
\f[R]
768
.fi
769
.RE
770
.TP
771
\f[V]--link-modularity-mismatch\f[R] (\f[V]warn\f[R]|\f[V]info\f[R])
772
Specifies whether external documentation with wrong modularity (e.g.
773
non-modular documentation for a modular library, or the reverse case)
774
should be reported as a warning (\f[V]warn\f[R]) or just a message
775
(\f[V]info\f[R]).
776
The default behavior is to report a warning.
777
.TP
778
\f[V]-linkoffline\f[R] \f[I]url1\f[R] \f[I]url2\f[R]
779
This option is a variation of the \f[V]-link\f[R] option.
780
They both create links to \f[V]javadoc\f[R] generated documentation for
781
externally referenced classes.
782
You can specify multiple \f[V]-linkoffline\f[R] options in a specified
783
\f[V]javadoc\f[R] tool run.
784
.RS
785
.PP
786
Use the \f[V]-linkoffline\f[R] option when:
787
.IP \[bu] 2
788
Linking to a document on the web that the \f[V]javadoc\f[R] tool
789
can\[aq]t access through a web connection
790
.IP \[bu] 2
791
The \f[V]package-list\f[R] or \f[V]element-list\f[R] file of the
792
external document either isn\[aq]t accessible or doesn\[aq]t exist at
793
the URL location, but does exist at a different location and can be
794
specified by either the \f[V]package-list\f[R] or \f[V]element-list\f[R]
795
file (typically local).
796
.PP
797
\f[I]Note:\f[R] The \f[V]package-list\f[R] and \f[V]element-list\f[R]
798
files are generated by the \f[V]javadoc\f[R] tool when generating the
799
API documentation and should not be modified by the user.
800
.PP
801
If \f[I]url1\f[R] is accessible only on the World Wide Web, then the
802
\f[V]-linkoffline\f[R] option removes the constraint that the
803
\f[V]javadoc\f[R] tool must have a web connection to generate
804
documentation.
805
.PP
806
Another use of the \f[V]-linkoffline\f[R] option is as a work-around to
807
update documents.
808
After you have run the \f[V]javadoc\f[R] tool on a full set of packages
809
or modules, you can run the \f[V]javadoc\f[R] tool again on a smaller
810
set of changed packages or modules, so that the updated files can be
811
inserted back into the original set.
812
.PP
813
For example, the \f[V]-linkoffline\f[R] option takes two arguments.
814
The first is for the string to be embedded in the \f[V]<a href>\f[R]
815
links, and the second tells the \f[V]javadoc\f[R] tool where to find
816
either the \f[V]package-list\f[R] or \f[V]element-list\f[R] file.
817
.PP
818
The \f[I]url1\f[R] or \f[I]url2\f[R] value is the absolute or relative
819
URL of the directory that contains the external \f[V]javadoc\f[R]
820
generated documentation that you want to link to.
821
When relative, the value should be the relative path from the
822
destination directory (specified with the \f[V]-d\f[R] option) to the
823
root of the packages being linked to.
824
See \f[I]url\f[R] in the \f[V]-link\f[R] option.
825
.RE
826
.TP
827
\f[V]--link-platform-properties\f[R] \f[I]url\f[R]
828
Specifies a properties file used to configure links to platform
829
documentation.
830
.RS
831
.PP
832
The \f[I]url\f[R] argument is expected to point to a properties file
833
containing one or more entries with the following format, where
834
\f[V]<version>\f[R] is the platform version as passed to the
835
\f[V]--release\f[R] or \f[V]--source\f[R] option and \f[V]<url>\f[R] is
836
the base URL of the corresponding platform API documentation:
837
.IP
838
.nf
839
\f[CB]
840
doclet.platform.docs.<version>=<url>
841
\f[R]
842
.fi
843
.PP
844
For instance, a properties file containing URLs for releases 15 to 17
845
might contain the following lines:
846
.IP
847
.nf
848
\f[CB]
849
doclet.platform.docs.15=https://example.com/api/15/
850
doclet.platform.docs.16=https://example.com/api/16/
851
doclet.platform.docs.17=https://example.com/api/17/
852
\f[R]
853
.fi
854
.PP
855
If the properties file does not contain an entry for a particular
856
release no platform links are generated.
857
.RE
858
.TP
859
\f[V]-linksource\f[R]
860
Creates an HTML version of each source file (with line numbers) and adds
861
links to them from the standard HTML documentation.
862
Links are created for classes, interfaces, constructors, methods, and
863
fields whose declarations are in a source file.
864
Otherwise, links aren\[aq]t created, such as for default constructors
865
and generated classes.
866
.RS
867
.PP
868
This option exposes all private implementation details in the included
869
source files, including private classes, private fields, and the bodies
870
of private methods, regardless of the \f[V]-public\f[R],
871
\f[V]-package\f[R], \f[V]-protected\f[R], and \f[V]-private\f[R]
872
options.
873
Unless you also use the \f[V]-private\f[R] option, not all private
874
classes or interfaces are accessible through links.
875
.PP
876
Each link appears on the name of the identifier in its declaration.
877
For example, the link to the source code of the \f[V]Button\f[R] class
878
would be on the word \f[V]Button\f[R]:
879
.IP
880
.nf
881
\f[CB]
882
public class Button extends Component implements Accessible
883
\f[R]
884
.fi
885
.PP
886
The link to the source code of the \f[V]getLabel\f[R] method in the
887
\f[V]Button\f[R] class is on the word \f[V]getLabel\f[R]:
888
.IP
889
.nf
890
\f[CB]
891
public String getLabel()
892
\f[R]
893
.fi
894
.RE
895
.TP
896
\f[V]--main-stylesheet\f[R] \f[I]file\f[R] or \f[V]-stylesheetfile\f[R] \f[I]file\f[R]
897
Specifies the path of an alternate stylesheet file that contains the
898
definitions for the CSS styles used in the generated documentation.
899
This option lets you override the default.
900
If you do not specify the option, the \f[V]javadoc\f[R] tool will create
901
and use a default stylesheet.
902
The file name can be any name and isn\[aq]t restricted to
903
\f[V]stylesheet.css\f[R].
904
The \f[V]--main-stylesheet\f[R] option is the preferred form.
905
.RS
906
.PP
907
Command-line example:
908
.IP
909
.nf
910
\f[CB]
911
javadoc --main-stylesheet main_stylesheet.css pkg_foo
912
\f[R]
913
.fi
914
.RE
915
.TP
916
\f[V]-nocomment\f[R]
917
Suppresses the entire comment body, including the main description and
918
all tags, and generate only declarations.
919
This option lets you reuse source files that were originally intended
920
for a different purpose so that you can produce skeleton HTML
921
documentation during the early stages of a new project.
922
.TP
923
\f[V]-nodeprecated\f[R]
924
Prevents the generation of any deprecated API in the documentation.
925
This does what the \f[V]-nodeprecatedlist\f[R] option does, and it
926
doesn\[aq]t generate any deprecated API throughout the rest of the
927
documentation.
928
This is useful when writing code when you don\[aq]t want to be
929
distracted by the deprecated code.
930
.TP
931
\f[V]-nodeprecatedlist\f[R]
932
Prevents the generation of the file that contains the list of deprecated
933
APIs (\f[V]deprecated-list.html\f[R]) and the link in the navigation bar
934
to that page.
935
The \f[V]javadoc\f[R] tool continues to generate the deprecated API
936
throughout the rest of the document.
937
This is useful when your source code contains no deprecated APIs, and
938
you want to make the navigation bar cleaner.
939
.TP
940
\f[V]--no-fonts\f[R]
941
Prevents inclusion of font files in the generated documentation.
942
This can be useful if the documentation uses a custom stylesheet which
943
does not use the default fonts.
944
.TP
945
\f[V]-nohelp\f[R]
946
Omits the \f[B]HELP\f[R] link in the navigation bar at the top of each
947
generated page.
948
.TP
949
\f[V]-noindex\f[R]
950
Omits the index from the generated documents.
951
The index is produced by default.
952
.TP
953
\f[V]-nonavbar\f[R]
954
Prevents the generation of the navigation bar and header.
955
The \f[V]-nonavbar\f[R] option has no effect on the \f[V]-bottom\f[R]
956
option.
957
The \f[V]-nonavbar\f[R] option is useful when you are interested only in
958
the content and have no need for navigation, such as when you are
959
converting the files to PostScript or PDF for printing only.
960
.TP
961
\f[V]--no-platform-links\f[R]
962
Prevents the generation of links to platform documentation.
963
These links are generated by default.
964
.TP
965
\f[V]-noqualifier\f[R] \f[I]name1\f[R]\f[V],\f[R]\f[I]name2...\f[R]
966
Excludes the list of qualifiers from the output.
967
The package name is removed from places where class or interface names
968
appear.
969
For historical reasons, \f[V]:\f[R] can be used anywhere in the argument
970
as a separator instead of \f[V],\f[R].
971
.RS
972
.PP
973
The following example omits all package qualifiers:
974
\f[V]-noqualifier all\f[R].
975
.PP
976
The following example omits \f[V]java.lang\f[R] and \f[V]java.io\f[R]
977
package qualifiers: \f[V]-noqualifier java.lang:java.io\f[R].
978
.PP
979
The following example omits package qualifiers starting with
980
\f[V]java\f[R] and \f[V]com.sun\f[R] subpackages, but not
981
\f[V]javax: -noqualifier java.*:com.sun.*\f[R].
982
.PP
983
Where a package qualifier would appear due to the previous behavior, the
984
name can be suitably shortened.
985
This rule is in effect whether or not the \f[V]-noqualifier\f[R] option
986
is used.
987
.RE
988
.TP
989
\f[V]-nosince\f[R]
990
Omits from the generated documentation the \f[V]Since\f[R] sections
991
derived from any \f[V]since\f[R] tags.
992
.TP
993
\f[V]-notimestamp\f[R]
994
Suppresses the time stamp, which is hidden in an HTML comment in the
995
generated HTML near the top of each page.
996
The \f[V]-notimestamp\f[R] option is useful when you want to run the
997
\f[V]javadoc\f[R] tool on two source bases and compare them, because it
998
prevents time stamps from causing a difference (which would otherwise be
999
a difference on every page).
1000
The time stamp includes the \f[V]javadoc\f[R] tool release number.
1001
.TP
1002
\f[V]-notree\f[R]
1003
Omits the class and interface hierarchy pages from the generated
1004
documents.
1005
These are the pages you reach using the \f[B]TREE\f[R] link in the
1006
navigation bar.
1007
The hierarchy is produced by default.
1008
.TP
1009
\f[V]--override-methods\f[R] (\f[V]detail\f[R]|\f[V]summary\f[R])
1010
Documents overridden methods in the detail or summary sections.
1011
The default is \f[V]detail\f[R].
1012
.TP
1013
\f[V]-overview\f[R] \f[I]filename\f[R]
1014
Specifies that the \f[V]javadoc\f[R] tool should retrieve the content
1015
for the overview documentation from the file specified by
1016
\f[I]filename\f[R] and place it on the Overview page
1017
(\f[V]overview-summary.html\f[R]).
1018
If the \f[I]filename\f[R] is a relative path, it is evaluated relative
1019
to the current working directory.
1020
.RS
1021
.PP
1022
The file may be an HTML file, with a filename ending in \f[V].html\f[R],
1023
or a Markdown file, with a filename ending in \f[V].md\f[R].
1024
If the file is an HTML file, the content for the overview documentation
1025
is taken from the \f[V]<main>\f[R] element in the file, if one is
1026
present, or from the \f[V]<body>\f[R] element is there is no
1027
\f[V]<main>\f[R] element.
1028
If the file is a Markdown file, the entire content of the file is used.
1029
.PP
1030
The title on the overview page is set by \f[V]-doctitle\f[R].
1031
.PP
1032
\f[I]Note:\f[R] older versions of the \f[V]javadoc\f[R] tool assumed
1033
that any use of this option was for an HTML file, and allowed any
1034
extension for the \f[I]filename\f[R].
1035
.RE
1036
.TP
1037
\f[V]-serialwarn\f[R]
1038
Reports compile-time warnings for missing \f[V]\[at]serial\f[R] tags.
1039
By default, Javadoc reports no serial warnings.
1040
Use this option to display the serial warnings, which helps to properly
1041
document default serializable fields and \f[V]writeExternal\f[R]
1042
methods.
1043
.TP
1044
\f[V]--since\f[R] \f[I]release\f[R](\f[V],\f[R]\f[I]release\f[R])*
1045
Generates documentation for APIs that were added or newly deprecated in
1046
the specified \f[I]release\f[R]s.
1047
.RS
1048
.PP
1049
If the \f[V]\[at]since\f[R] tag in the \f[V]javadoc\f[R] comment of an
1050
element in the documented source code matches a \f[I]release\f[R] passed
1051
as the option argument, information about the element and the release it
1052
was added in is included in a \[dq]New API\[dq] page.
1053
.PP
1054
If the \[dq]Deprecated API\[dq] page is generated and the
1055
\f[V]since\f[R] element of the \f[V]java.lang.Deprecated\f[R] annotation
1056
of a documented element matches a \f[I]release\f[R] in the option
1057
arguments, information about the release the element was deprecated in
1058
is added to the \[dq]Deprecated API\[dq] page.
1059
.PP
1060
Releases are compared using case-sensitive string comparison.
1061
.RE
1062
.TP
1063
\f[V]--since-label\f[R] \f[I]text\f[R]
1064
Specifies the \f[I]text\f[R] to use in the heading of the \[dq]New
1065
API\[dq] page.
1066
This may contain information about the releases covered in the page,
1067
e.g.
1068
\[dq]New API in release 2.0\[dq], or \[dq]New API since release 1\[dq].
1069
.TP
1070
\f[V]--snippet-path\f[R] \f[I]snippetpathlist\f[R]
1071
Specifies the search paths for finding files for external snippets.
1072
The \f[I]snippetpathlist\f[R] can contain multiple paths by separating
1073
them with the platform path separator (\f[V];\f[R] on Windows;
1074
\f[V]:\f[R] on other platforms.)
1075
The standard doclet first searches the \f[V]snippet-files\f[R]
1076
subdirectory in the package containing the snippet, and then searches
1077
all the directories in the given list.
1078
.TP
1079
\f[V]-sourcetab\f[R] \f[I]tab-length\f[R]
1080
Specifies the number of spaces each tab uses in the source.
1081
.TP
1082
\f[V]--spec-base-url\f[R] \f[I]url\f[R]
1083
Specifies the base URL for relative URLs in \f[V]\[at]spec\f[R] tags, to
1084
be used when generating links to any external specifications.
1085
It can either be an absolute URL, or a relative URL, in which case it is
1086
evaluated relative to the base directory of the generated output files.
1087
The default value is equivalent to \f[V]{\[at]docRoot}/../specs\f[R].
1088
.TP
1089
\f[V]-splitindex\f[R]
1090
Splits the index file into multiple files, alphabetically, one file per
1091
letter, plus a file for any index entries that start with
1092
non-alphabetical symbols.
1093
.TP
1094
\f[V]-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
1095
Specifies a custom tag with a single argument.
1096
For the \f[V]javadoc\f[R] tool to spell-check tag names, it is important
1097
to include a \f[V]-tag\f[R] option for every custom tag that is present
1098
in the source code, disabling (with \f[V]X\f[R]) those that aren\[aq]t
1099
being output in the current run.
1100
The colon (\f[V]:\f[R]) is always the separator.
1101
To include a colon in the tag name, escape it with a backward slash
1102
(\f[V]\[rs]\f[R]).
1103
The \f[V]-tag\f[R] option outputs the tag heading, \f[I]header\f[R], in
1104
bold, followed on the next line by the text from its single argument.
1105
Similar to any block tag, the argument text can contain inline tags,
1106
which are also interpreted.
1107
The output is similar to standard one-argument tags, such as the
1108
\f[V]\[at]return\f[R] and \f[V]\[at]author\f[R] tags.
1109
Omitting a \f[I]header\f[R] value causes the \f[I]name\f[R] to be the
1110
heading.
1111
\f[I]locations\f[R] is a list of characters specifying the kinds of
1112
declarations in which the tag may be used.
1113
The following characters may be used, in either uppercase or lowercase:
1114
.RS
1115
.IP \[bu] 2
1116
\f[V]A\f[R]: all declarations
1117
.IP \[bu] 2
1118
\f[V]C\f[R]: constructors
1119
.IP \[bu] 2
1120
\f[V]F\f[R]: fields
1121
.IP \[bu] 2
1122
\f[V]M\f[R]: methods
1123
.IP \[bu] 2
1124
\f[V]O\f[R]: the overview page and other documentation files in
1125
\f[V]doc-files\f[R] subdirectories
1126
.IP \[bu] 2
1127
\f[V]P\f[R]: packages
1128
.IP \[bu] 2
1129
\f[V]S\f[R]: modules
1130
.IP \[bu] 2
1131
\f[V]T\f[R]: types (classes and interfaces)
1132
.IP \[bu] 2
1133
\f[V]X\f[R]: nowhere: the tag is disabled, and will be ignored
1134
.PP
1135
The order in which tags are given on the command line will be used as
1136
the order in which the tags appear in the generated output.
1137
You can include standard tags in the order given on the command line by
1138
using the \f[V]-tag\f[R] option with no \f[I]locations\f[R] or
1139
\f[I]header\f[R].
1140
.RE
1141
.TP
1142
\f[V]-taglet\f[R] \f[I]class\f[R]
1143
Specifies the fully qualified name of the taglet used in generating the
1144
documentation for that tag.
1145
Use the fully qualified name for the \f[I]class\f[R] value.
1146
This taglet also defines the number of text arguments that the custom
1147
tag has.
1148
The taglet accepts those arguments, processes them, and generates the
1149
output.
1150
.RS
1151
.PP
1152
Taglets are useful for block or inline tags.
1153
They can have any number of arguments and implement custom behavior,
1154
such as making text bold, formatting bullets, writing out the text to a
1155
file, or starting other processes.
1156
Taglets can only determine where a tag should appear and in what form.
1157
All other decisions are made by the doclet.
1158
A taglet can\[aq]t do things such as remove a class name from the list
1159
of included classes.
1160
However, it can execute side effects, such as printing the tag\[aq]s
1161
text to a file or triggering another process.
1162
Use the \f[V]-tagletpath\f[R] option to specify the path to the taglet.
1163
The following example inserts the To Do taglet after Parameters and
1164
ahead of Throws in the generated pages.
1165
.IP
1166
.nf
1167
\f[CB]
1168
-taglet com.sun.tools.doclets.ToDoTaglet
1169
-tagletpath /home/taglets
1170
-tag return
1171
-tag param
1172
-tag todo
1173
-tag throws
1174
-tag see
1175
\f[R]
1176
.fi
1177
.PP
1178
Alternately, you can use the \f[V]-taglet\f[R] option in place of its
1179
\f[V]-tag\f[R] option, but that might be difficult to read.
1180
.RE
1181
.TP
1182
\f[V]-tagletpath\f[R] \f[I]tagletpathlist\f[R]
1183
Specifies the search paths for finding taglet class files.
1184
The \f[I]tagletpathlist\f[R] can contain multiple paths by separating
1185
them with the platform path separator (\f[V];\f[R] on Windows;
1186
\f[V]:\f[R] on other platforms.)
1187
The \f[V]javadoc\f[R] tool searches all subdirectories of the specified
1188
paths.
1189
.TP
1190
\f[V]-top\f[R] \f[I]html-code\f[R]
1191
Specifies the text to be placed at the top of each output file.
1192
.TP
1193
\f[V]-use\f[R]
1194
Creates class and package usage pages.
1195
Includes one Use page for each documented class and package.
1196
The page describes what packages, classes, methods, constructors, and
1197
fields use any API of the specified class or package.
1198
Given class C, things that use class C would include subclasses of C,
1199
fields declared as C, methods that return C, and methods and
1200
constructors with parameters of type C.
1201
For example, you can look at the Use page for the \f[V]String\f[R] type.
1202
Because the \f[V]getName\f[R] method in the \f[V]java.awt.Font\f[R]
1203
class returns type \f[V]String\f[R], the \f[V]getName\f[R] method uses
1204
\f[V]String\f[R] and so the \f[V]getName\f[R] method appears on the Use
1205
page for \f[V]String\f[R].
1206
This documents only uses of the API, not the implementation.
1207
When a method uses \f[V]String\f[R] in its implementation, but
1208
doesn\[aq]t take a string as an argument or return a string, that
1209
isn\[aq]t considered a use of \f[V]String\f[R].
1210
To access the generated Use page, go to the class or package and click
1211
the \f[B]USE\f[R] link in the navigation bar.
1212
.TP
1213
\f[V]-version\f[R]
1214
Includes the text of any \f[V]version\f[R] tags in the generated
1215
documentation.
1216
This text is omitted by default.
1217
Note: To find out what version of the \f[V]javadoc\f[R] tool you are
1218
using, use the \f[V]--version\f[R] option (with two hyphens).
1219
.TP
1220
\f[V]-windowtitle\f[R] \f[I]title\f[R]
1221
Specifies the title to be placed in the HTML \f[V]<title>\f[R] tag.
1222
The text specified in the \f[V]title\f[R] tag appears in the window
1223
title and in any browser bookmarks (favorite places) that someone
1224
creates for this page.
1225
This title should not contain any HTML tags because a browser will not
1226
interpret them correctly.
1227
Use escape characters on any internal quotation marks within the
1228
\f[V]title\f[R] tag.
1229
If the \f[V]-windowtitle\f[R] option is omitted, then the
1230
\f[V]javadoc\f[R] tool uses the value of the \f[V]-doctitle\f[R] option
1231
for the \f[V]-windowtitle\f[R] option.
1232
For example,
1233
\f[V]javadoc -windowtitle \[dq]My Library\[dq] com.mypackage\f[R].
1234
.SS Extra Options for the Standard Doclet
1235
.PP
1236
The following are additional options provided by the standard doclet and
1237
are subject to change without notice.
1238
Additional options are less commonly used or are otherwise regarded as
1239
advanced.
1240
.TP
1241
\f[V]--date\f[R] \f[I]date-and-time\f[R]
1242
Specifies the value to be used to timestamp the generated pages, in
1243
\f[B]ISO 8601\f[R]
1244
[https://www.iso.org/iso-8601-date-and-time-format.html] format.
1245
The specified value must be within 10 years of the current date and
1246
time.
1247
It is an error to specify both \f[V]-notimestamp\f[R] and
1248
\f[V]--date\f[R].
1249
Using a specific value means the generated documentation can be part of
1250
a \f[B]reproducible build\f[R] [https://reproducible-builds.org/].
1251
If the option is not given, the default value is the current date and
1252
time.
1253
For example:
1254
.RS
1255
.IP
1256
.nf
1257
\f[CB]
1258
javadoc --date 2022-02-01T17:41:59-08:00 mypackage
1259
\f[R]
1260
.fi
1261
.RE
1262
.TP
1263
\f[V]--legal-notices\f[R] (\f[V]default\f[R]|\f[V]none\f[R]|\f[I]directory\f[R])
1264
Specifies the location from which to copy legal files to the generated
1265
documentation.
1266
If the option is not specified or is used with the value
1267
\f[V]default\f[R], the files are copied from the default location.
1268
If the argument is used with value \f[V]none\f[R], no files are copied.
1269
Every other argument is interpreted as directory from which to copy the
1270
legal files.
1271
.TP
1272
\f[V]--no-frames\f[R]
1273
This option is no longer supported and reports a warning.
1274
.TP
1275
\f[V]-Xdoclint\f[R]
1276
Enables recommended checks for problems in documentation comments.
1277
.RS
1278
.PP
1279
By default, the \f[V]-Xdoclint\f[R] option is enabled.
1280
Disable it with the option \f[V]-Xdoclint:none\f[R].
1281
.PP
1282
For more details, see \f[B]DocLint\f[R].
1283
.RE
1284
.TP
1285
\f[V]-Xdoclint:\f[R]\f[I]flag\f[R],\f[I]flag\f[R],...
1286
Enables or disables specific checks for different kinds of issues in
1287
documentation comments.
1288
.RS
1289
.PP
1290
Each \f[I]flag\f[R] can be one of \f[V]all\f[R], \f[V]none\f[R], or
1291
\f[V][-]\f[R]\f[I]group\f[R] where \f[I]group\f[R] has one of the
1292
following values: \f[V]accessibility\f[R], \f[V]html\f[R],
1293
\f[V]missing\f[R], \f[V]reference\f[R], \f[V]syntax\f[R].
1294
For more details on these values, see \f[B]DocLint Groups\f[R].
1295
.PP
1296
When specifying two or more flags, you can either use a single
1297
\f[V]-Xdoclint:...\f[R] option, listing all the desired flags, or you
1298
can use multiple options giving one or more flag in each option.
1299
For example, use either of the following commands to check for the HTML,
1300
syntax, and accessibility issues in the file \f[V]MyFile.java\f[R].
1301
.IP
1302
.nf
1303
\f[CB]
1304
javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility MyFile.java
1305
javadoc -Xdoclint:html,syntax,accessibility MyFile.java
1306
\f[R]
1307
.fi
1308
.PP
1309
The following examples illustrate how to change what DocLint reports:
1310
.IP \[bu] 2
1311
\f[V]-Xdoclint:none\f[R] --- disables all checks
1312
.IP \[bu] 2
1313
\f[V]-Xdoclint:\f[R]\f[I]group\f[R] --- enables \f[I]group\f[R] checks
1314
.IP \[bu] 2
1315
\f[V]-Xdoclint:all\f[R] --- enables all groups of checks
1316
.IP \[bu] 2
1317
\f[V]-Xdoclint:all,-\f[R]\f[I]group\f[R] --- enables all checks except
1318
\f[I]group\f[R] checks
1319
.PP
1320
For more details, see \f[B]DocLint\f[R].
1321
.RE
1322
.TP
1323
\f[V]-Xdoclint/package:\f[R][\f[V]-\f[R]]\f[I]packages\f[R]
1324
Enables or disables checks in specific packages.
1325
\f[I]packages\f[R] is a comma separated list of package specifiers.
1326
A package specifier is either a qualified name of a package or a package
1327
name prefix followed by \f[V]*\f[R], which expands to all subpackages of
1328
the given package.
1329
Prefix the package specifier with \f[V]-\f[R] to disable checks for the
1330
specified packages.
1331
.RS
1332
.PP
1333
For more details, see \f[B]DocLint\f[R].
1334
.RE
1335
.TP
1336
\f[V]-Xdocrootparent\f[R] \f[I]url\f[R]
1337
Replaces all \f[V]\[at]docRoot\f[R] items followed by \f[V]/..\f[R] in
1338
documentation comments with \f[I]url\f[R].
1339
.SH DOCLINT
1340
.PP
1341
DocLint provides the ability to check for possible problems in
1342
documentation comments.
1343
Problems may be reported as warnings or errors, depending on their
1344
severity.
1345
For example, a missing comment may be bad style that deserves a warning,
1346
but a link to an unknown Java declaration is more serious and deserves
1347
an error.
1348
Problems are organized into \f[B]groups\f[R], and options can be used to
1349
enable or disable messages in one or more groups.
1350
Within the source code, messages in one or more groups can be
1351
\f[B]suppressed\f[R] by using \f[V]\[at]SuppressWarnings\f[R]
1352
annotations.
1353
.PP
1354
When invoked from \f[V]javadoc\f[R], by default DocLint checks all
1355
comments that are used in the generated documentation.
1356
It thus relies on other command-line options to determine which
1357
declarations, and which corresponding documentation comments will be
1358
included.
1359
\f[I]Note:\f[R] this may mean that even comments on some private members
1360
of serializable classes will also be checked, if the members need to be
1361
documented in the generated \f[V]Serialized Forms\f[R] page.
1362
.PP
1363
In contrast, when DocLint is invoked from \f[V]javac\f[R], DocLint
1364
solely relies on the various \f[V]-Xdoclint...\f[R] options to determine
1365
which documentation comments to check.
1366
.PP
1367
DocLint doesn\[aq]t attempt to fix invalid input, it just reports it.
1368
.PP
1369
\f[I]Note:\f[R] DocLint doesn\[aq]t guarantee the completeness of these
1370
checks.
1371
In particular, it isn\[aq]t a full HTML compliance checker.
1372
The goal is to just report common errors in a convenient manner.
1373
.SS Groups
1374
.PP
1375
The checks performed by DocLint are organized into groups.
1376
The warnings and errors in each group can be enabled or disabled with
1377
command-line options, or suppressed with \f[V]\[at]SuppressWarnings\f[R]
1378
annotations.
1379
.PP
1380
The groups are as follows:
1381
.IP \[bu] 2
1382
\f[V]accessibility\f[R] --- Checks for issues related to accessibility.
1383
For example, no \f[V]alt\f[R] attribute specified in an \f[V]<img>\f[R]
1384
element, or no caption or summary attributes specified in a
1385
\f[V]<table>\f[R] element.
1386
.RS 2
1387
.PP
1388
Issues are reported as errors if a downstream validation tool might be
1389
expected to report an error in the files generated by \f[V]javadoc\f[R].
1390
.PP
1391
For reference, see the \f[B]Web Content Accessibility Guidelines\f[R]
1392
[https://www.w3.org/WAI/standards-guidelines/wcag/].
1393
.RE
1394
.IP \[bu] 2
1395
\f[V]html\f[R] --- Detects common high-level HTML issues.
1396
For example, putting block elements inside inline elements, or not
1397
closing elements that require an end tag.
1398
.RS 2
1399
.PP
1400
Issues are reported as errors if a downstream validation tool might be
1401
expected to report an error in the files generated by \f[V]javadoc\f[R].
1402
.PP
1403
For reference, see the \f[B]HTML Living Standard\f[R]
1404
[https://html.spec.whatwg.org/multipage/].
1405
.RE
1406
.IP \[bu] 2
1407
\f[V]missing\f[R] --- Checks for missing documentation comments or tags.
1408
For example, a missing comment on a class declaration, or a missing
1409
\f[V]\[at]param\f[R] or \f[V]\[at]return\f[R] tag in the comment for a
1410
method declaration.
1411
.RS 2
1412
.PP
1413
Issues related to missing items are typically reported as warnings
1414
because they are unlikely to be reported as errors by downstream
1415
validation tools that may be used to check the output generated by
1416
\f[V]javadoc\f[R].
1417
.RE
1418
.IP \[bu] 2
1419
\f[V]reference\f[R] --- Checks for issues relating to the references to
1420
Java API elements from documentation comment tags.
1421
For example, the reference in \f[V]\[at]see\f[R] or
1422
\f[V]{\[at]link ...}\f[R] cannot be found, or a bad name is given for
1423
\f[V]\[at]param\f[R] or \f[V]\[at]throws\f[R].
1424
.RS 2
1425
.PP
1426
Issues are typically reported as errors because while the issue may not
1427
cause problems in the generated files, the author has likely made a
1428
mistake that will lead to incorrect or unexpected documentation.
1429
.RE
1430
.IP \[bu] 2
1431
\f[V]syntax\f[R] --- Checks for low-level syntactic issues in
1432
documentation comments.
1433
For example, unescaped angle brackets (\f[V]<\f[R] and \f[V]>\f[R]) and
1434
ampersands (\f[V]&\f[R]) and invalid documentation comment tags.
1435
.RS 2
1436
.PP
1437
Issues are typically reported as errors because the issues may lead to
1438
incorrect or unexpected documentation.
1439
.RE
1440
.SS Suppressing Messages
1441
.PP
1442
DocLint checks for and recognizes two strings that may be present in the
1443
arguments for an \f[V]\[at]SuppressWarnings\f[R] annotation.
1444
.IP \[bu] 2
1445
\f[V]doclint\f[R]
1446
.IP \[bu] 2
1447
\f[V]doclint:\f[R]\f[I]LIST\f[R]
1448
.PP
1449
where \f[I]LIST\f[R] is a comma-separated list of one or more of
1450
\f[V]accessibility\f[R], \f[V]html\f[R], \f[V]missing\f[R],
1451
\f[V]reference\f[R], \f[V]syntax\f[R].
1452
.PP
1453
The names in \f[I]LIST\f[R] are the same \f[B]group\f[R] names supported
1454
by the command-line \f[V]-Xdoclint\f[R] option for \f[V]javac\f[R] and
1455
\f[V]javadoc\f[R].
1456
(This is the same convention honored by the \f[V]javac\f[R]
1457
\f[V]-Xlint\f[R] option and the corresponding names supported by
1458
\f[V]\[at]SuppressWarnings\f[R].)
1459
.PP
1460
The names in \f[I]LIST\f[R] can equivalently be specified in separate
1461
arguments of the annotation.
1462
For example, the following are equivalent:
1463
.IP \[bu] 2
1464
\f[V]\[at]SuppressWarnings(\[dq]doclint:accessibility,missing\[dq])\f[R]
1465
.IP \[bu] 2
1466
\f[V]\[at]SuppressWarnings(\[dq]doclint:accessibility\[dq], \[dq]doclint:missing\[dq])\f[R]
1467
.PP
1468
When DocLint detects an issue in a documentation comment, it checks for
1469
the presence of \f[V]\[at]SuppressWarnings\f[R] on the associated
1470
declaration and on all lexically enclosing declarations.
1471
The issue will be ignored if any such annotation is found containing the
1472
simple string \f[V]doclint\f[R] or the longer form
1473
\f[V]doclint:LIST\f[R] where \f[I]LIST\f[R] contains the name of the
1474
group for the issue.
1475
.PP
1476
\f[I]Note:\f[R] as with other uses of \f[V]\[at]SuppressWarnings\f[R],
1477
using the annotation on a module or package declaration only affects
1478
that declaration; it does not affect the contents of the module or
1479
package in other source files.
1480
.PP
1481
All messages related to an issue are suppressed by the presence of an
1482
appropriate \f[V]\[at]SuppressWarnings\f[R] annotation: this includes
1483
errors as well as warnings.
1484
.PP
1485
\f[I]Note:\f[R] It is only possible to \f[I]suppress\f[R] messages.
1486
If an annotation of \f[V]\[at]SuppressWarnings(\[dq]doclint\[dq])\f[R]
1487
is given on a top-level declaration, all DocLint messages for that
1488
declaration and any enclosed declarations will be suppressed; it is not
1489
possible to selectively re-enable messages for issues in enclosed
1490
declarations.
1491
.SS Comparison with downstream validation tools
1492
.PP
1493
DocLint is a utility built into \f[V]javac\f[R] and \f[V]javadoc\f[R]
1494
that checks the content of documentation comments, as found in source
1495
files.
1496
In contrast, downstream validation tools can be used to validate the
1497
output generated from those documentation comments by \f[V]javadoc\f[R]
1498
and the standard doclet.
1499
.PP
1500
Although there is some overlap in functionality, the two mechanisms are
1501
different and each has its own strengths and weaknesses.
1502
.IP \[bu] 2
1503
Downstream validation tools can check the end result of any generated
1504
documentation, as it will be seen by the end user.
1505
This includes content from all sources, including documentation
1506
comments, the standard doclet itself, user-provided taglets, and content
1507
supplied via command-line options.
1508
Because such tools are analyzing complete HTML pages, they can do more
1509
complete checks than can DocLint.
1510
However, when a problem is found in the generated pages, it can be
1511
harder to track down exactly where in the build pipeline the problem
1512
needs to be fixed.
1513
.IP \[bu] 2
1514
DocLint checks the content of documentation comments, in source files.
1515
This makes it very easy to identify the exact position of any issues
1516
that may be found.
1517
DocLint can also detect some semantic errors in documentation comments
1518
that downstream tools cannot detect, such as missing comments, using an
1519
\f[V]\[at]return\f[R] tag in a method returning \f[V]void\f[R], or an
1520
\f[V]\[at]param\f[R] tag describing a non-existent parameter.
1521
But by its nature, DocLint cannot report on problems such as missing
1522
links, or errors in user-provided custom taglets, or problems in the
1523
standard doclet itself.
1524
It also cannot reliably detect errors in documentation comments at the
1525
boundaries between content in a documentation comment and content
1526
generated by a custom taglet.
1527