1javadoc(1) General Commands Manual javadoc(1)
2
6 javadoc - The Java API Documentation Generator
7 Generates HTML pages of API documentation from Java source files. This
9 document contains Javadoc examples for Solaris.
10
12 javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpack‐
13 ages pkg1:pkg2:... ] [ @argfiles ]
14 Arguments can be in any order. See processing of Source Files for
16 details on how the Javadoc tool determines which ".java" files to
17 process.
18 options
20 Command-line options, as specified in this document. To see a
21 typical use of javadoc options, see Real-World Example.
22 packagenames
24 A series of names of packages, separated by spaces, such as
25 java.lang java.lang.reflect java.awt. You must separately specify
26 each package you want to document. Wildcards are not allowed; use
27 -subpackages for recursion. The Javadoc tool uses -sourcepath to
28 look for these package names. See Example - Documenting One or
29 More Packages
30 sourcefilenames
32 A series of source file names, separated by spaces, each of which
33 can begin with a path and contain a wildcard such as asterisk
34 (*). The Javadoc tool will process every file whose name ends
35 with ".java", and whose name, when stripped of that suffix, is
36 actually a legal class name (see the Java Language Specifica‐
37 tion). Therefore, you can name files with dashes (such as X-Buf‐
38 fer), or other illegal characters, to prevent them from being
39 documented. This is useful for test files and template files The
40 path that precedes the source file name determines where javadoc
41 will look for the file. (The Javadoc tool does not use -sour‐
42 cepath to look for these source file names.) Relative paths are
43 relative to the current directory, so passing in Button.java is
44 identical to ./Button.java. A source file name with an absolute
45 path and a wildcard, for example, is /home/src/java/awt/Graph‐
46 ics*.java. See Example - Documenting One or More Classes. You can
47 also mix packagenames and sourcefilenames, as in Example - Docu‐
48 menting Both Packages and Classes
49 -subpackages pkg1:pkg2:...
51 Generates documentation from source files in the specified pack‐
52 ages and recursively in their subpackages. An alternative to sup‐
53 plying packagenames or sourcefilenames.
54 @argfiles
56 One or more files that contain a list of Javadoc options, packa‐
57 genames and sourcefilenames in any order. Wildcards (*) and -J
58 options are not allowed in these files.
59
61 The Javadoc tool parses the declarations and documentation comments in
62 a set of Java source files and produces a corresponding set of HTML
63 pages describing (by default) the public and protected classes, nested
64 classes (but not anonymous inner classes), interfaces, constructors,
65 methods, and fields. You can use it to generate the API (Application
66 Programming Interface) documentation or the implementation documenta‐
67 tion for a set of source files.
68 You can run the Javadoc tool on entire packages, individual source
70 files, or both. When documenting entire packages, you can either use
71 -subpackages for traversing recursively down from a top-level direc‐
72 tory, or pass in an explicit list of package names. When documenting
73 individual source files, you pass in a list of source (.java) file‐
74 names. Examples are given at the end of this document. How Javadoc pro‐
75 cesses source files is covered next.
76 Processing of source files
78 The Javadoc tool processes files that end in ".java" plus other files
79 described under Source Files. If you run the Javadoc tool by explicitly
80 passing in individual source filenames, you can determine exactly which
81 ".java" files are processed. However, that is not how most developers
82 want to work, as it is simpler to pass in package names. The Javadoc
83 tool can be run three ways without explicitly specifying the source
84 filenames. You can (1) pass in package names, (2) use -subpackages, and
85 (3) use wildcards with source filenames (*.java). In these cases, the
86 Javadoc tool processes a ".java" file only if it fulfills all of the
87 following requirements:
88 o Its name, after stripping off the ".java" suffix, is actually a
90 legal class name (see the Java Language Specification for legal
91 characters)
92 o Its directory path relative to the root of the source tree is
94 actually a legal package name (after converting its separators to
95 dots)
96 o Its package statement contains the legal package name (specified
98 in the previous bullet)
99 Processing of links - During a run, the Javadoc tool automatically adds
101 cross-reference links to package, class and member names that are being
102 documented as part of that run. Links appear in several places:
103 o Declarations (return types, argument types, field types)
105 o "See Also" sections generated from @see tags
107 o In-line text generated from {@link} tags
109 o Exception names generated from @throws tags
111 o "Specified by" links to members in interfaces and "Overrides"
113 links to members in classes
114 o Summary tables listing packages, classes and members
116 o Package and class inheritance trees
118 o The index
120 You can add hyperlinks to existing text for classes not included on the
122 command line (but generated separately) by way of the -link and
123 -linkoffline options.
124 Other processing details - The Javadoc tool produces one complete docu‐
126 ment each time it is run; it cannot do incremental builds -- that is,
127 it cannot modify or directly incorporate results from previous runs of
128 the Javadoc tool. However, it can link to results from other runs, as
129 just mentioned.
130 As implemented, the Javadoc tool requires and relies on the java com‐
132 piler to do its job. The Javadoc tool calls part of javac to compile
133 the declarations, ignoring the member implementation. It builds a rich
134 internal representation of the classes, including the class hierarchy,
135 and "use" relationships, then generates the HTML from that. The Javadoc
136 tool also picks up user-supplied documentation from documentation com‐
137 ments in the source code.
138 In fact, the Javadoc tool will run on .java source files that are pure
140 stub files with no method bodies. This means you can write documenta‐
141 tion comments and run the Javadoc tool in the earliest stages of design
142 while creating the API, before writing the implementation.
143 Relying on the compiler ensures that the HTML output corresponds
145 exactly with the actual implementation, which may rely on implicit,
146 rather than explicit, source code. For example, the Javadoc tool docu‐
147 ments default constructors (see Java Language Specification) that are
148 present in the .class files but not in the source code.
149 In many cases, the Javadoc tool allows you to generate documentation
151 for source files whose code is incomplete or erroneous. This is a bene‐
152 fit that enables you to generate documentation before all debugging and
153 troubleshooting is done. For example, according to the Java Language
154 Specification, a class that contains an abstract method should itself
155 be declared abstract. The Javadoc tool does not check for this, and
156 would proceed without a warning, whereas the javac compiler stops on
157 this error. The Javadoc tool does do some primitive checking of doc
158 comments. Use the DocCheck doclet to check the doc comments more thor‐
159 oughly.
160 When the Javadoc tool builds its internal structure for the documenta‐
162 tion, it loads all referenced classes. Because of this, the Javadoc
163 tool must be able to find all referenced classes, whether bootstrap
164 classes, extensions, or user classes. For more about this, see How
165 Classes Are Found @
166 http://docs.oracle.com/javase/7/docs/technotes/tools/finding‐
167 classes.html. Generally speaking, classes you create must either be
168 loaded as an extension or in the Javadoc tool's class path.
169 Javadoc Doclets
171 You can customize the content and format of the Javadoc tool's output
172 by using doclets. The Javadoc tool has a default "built-in" doclet,
173 called the standard doclet, that generates HTML-formatted API documen‐
174 tation. You can modify or subclass the standard doclet, or write your
175 own doclet to generate HTML, XML, MIF, RTF or whatever output format
176 you'd like. Information about doclets and their use is at the following
177 locations:
178 o Javadoc Doclets @
180 http://docs.oracle.com/javase/7/docs/tech‐
181 notes/guides/javadoc/index.html
182 o The -doclet command-line option
184 When a custom doclet is not specified with the -doclet command line
186 option, the Javadoc tool will use the default standard doclet. The
187 javadoc tool has several command line options that are available
188 regardless of which doclet is being used. The standard doclet adds a
189 supplementary set of command line options. Both sets of options are
190 described below in the options section.
191 Related Documentation and Doclets
193 o Javadoc Enhancements @
194 http://docs.oracle.com/javase/7/docs/tech‐
195 notes/guides/javadoc/index.html for details about improvements
196 added in Javadoc.
197 o Javadoc FAQ @
199 http://java.sun.com/j2se/javadoc/faq/index.html for answers to
200 common questions, information about Javadoc-related tools, and
201 workarounds for bugs.
202 o How to Write Doc Comments for Javadoc @
204 http://www.oracle.com/technetwork/java/javase/documenta‐
205 tion/index-137868.html for more information about Sun conventions
206 for writing documentation comments.
207 o Requirements for Writing API Specifications @
209 http://java.sun.com/j2se/javadoc/writingapispecs/index.html -
210 Standard requirements used when writing the Java SE Platform Spec‐
211 ification. It can be useful whether you are writing API specifica‐
212 tions in source file documentation comments or in other formats.
213 It covers requirements for packages, classes, interfaces, fields
214 and methods to satisfy testable assertions.
215 o Documentation Comment Specification @
217 http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html
218 - The original specification on documentation comments, Chapter
219 18, Documentation Comments, in the Java Language Specification,
220 First Edition, by James Gosling, Bill Joy, and Guy Steele. (This
221 chapter was removed from the second edition.)
222 o DocCheck Doclet @
224 http://www.oracle.com/technetwork/java/javase/documenta‐
225 tion/index-141437.html - Checks doc comments in source files and
226 generates a report listing the errors and irregularities it finds.
227 It is part of the Doc Check Utilities.
228 o MIF Doclet @
230 http://java.sun.com/j2se/javadoc/mifdoclet/ - Can automate the
231 generation of API documentation in MIF, FrameMaker and PDF for‐
232 mats. MIF is Adobe FrameMaker's interchange format.
233 Terminology
235 The terms documentation comment, doc comment, main description, tag,
236 block tag, and in-line tag are described at Documentation Comments.
237 These other terms have specific meanings within the context of the
238 Javadoc tool:
239 generated document
241 The document generated by the javadoc tool from the doc comments
242 in Java source code. The default generated document is in HTML
243 and is created by the standard doclet.
244 name
246 A name of a program element written in the Java Language -- that
247 is, the name of a package, class, interface, field, constructor
248 or method. A name can be fully-qualified, such as
249 java.lang.String.equals(java.lang.Object), or partially-quali‐
250 fied, such as equals(Object).
251 documented classes
253 The classes and interfaces for which detailed documentation is
254 generated during a javadoc run. To be documented, the source
255 files must be available, their source filenames or package names
256 must be passed into the javadoc command, and they must not be
257 filtered out by their access modifier (public, protected, pack‐
258 age-private or private). We also refer to these as the classes
259 included in the javadoc output, or the included classes.
260 included classes
262 Classes and interfaces whose details are documented during a run
263 of the Javadoc tool. Same as documented classes.
264 excluded classes
266 Classes and interfaces whose details are not documented during a
267 run of the Javadoc tool.
268 referenced classes
270 The classes and interfaces that are explicitly referred to in the
271 definition (implementation) or doc comments of the documented
272 classes and interfaces. Examples of references include return
273 type, parameter type, cast type, extended class, implemented
274 interface, imported classes, classes used in method bodies, @see,
275 {@link}, {@linkplain}, and {@inheritDoc} tags. (Notice this defi‐
276 nition has changed since 1.3 @
277 http://docs.ora‐
278 cle.com/javase/1.3/docs/tooldocs/solaris/javadoc.html#referenced‐
279 classes.) When the Javadoc tool is run, it should load into mem‐
280 ory all of the referenced classes in javadoc's bootclasspath and
281 classpath. (The Javadoc tool prints a "Class not found" warning
282 for referenced classes not found.) The Javadoc tool can derive
283 enough information from the .class files to determine their exis‐
284 tence and the fully-qualified names of their members.
285 external referenced classes
287 The referenced classes whose documentation is not being generated
288 during a javadoc run. In other words, these classes are not
289 passed into the Javadoc tool on the command line. Links in the
290 generated documentation to those classes are said to be external
291 references or external links. For example, if you run the Javadoc
292 tool on only the java.awt package, then any class in java.lang,
293 such as Object, is an external referenced class. External refer‐
294 enced classes can be linked to using the -link and -linkoffline
295 options. An important property of an external referenced class is
296 that its source comments are normally not available to the
297 Javadoc run. In this case, these comments cannot be inherited.
298
300 The Javadoc tool will generate output originating from four different
301 types of "source" files: Java language source files for classes
302 (.java), package comment files, overview comment files, and miscella‐
303 neous unprocessed files. This section also covers test files and tem‐
304 plate files that can also be in the source tree, but which you want to
305 be sure not to document.
306 Class Source Code Files
308 Each class or interface and its members can have their own documenta‐
309 tion comments, contained in a .java file. For more details about these
310 doc comments, see Documentation Comments.
311 Package Comment Files
313 Each package can have its own documentation comment, contained in its
314 own "source" file, that the Javadoc tool will merge into the package
315 summary page that it generates. You typically include in this comment
316 any documentation that applies to the entire package.
317 To create a package comment file, you have a choice of two files to
319 place your comments:
320 o package-info.java - Can contain a package declaration, package
322 annotations, package comments and Javadoc tags. This file is gen‐
323 erally preferred over package.html.
324 o package.html - Can contain only package comments and Javadoc tags,
326 no package annotations.
327 A package may have a single package.html file or a single pack‐
329 age-info.java file but not both. Place either file in the package
330 directory in the source tree along with your .java files.
331 package-info.java - This file can contain a package comment of the fol‐
333 lowing structure -- the comment is placed before the package declara‐
334 tion:
335 File: java/applet/package-info.java
337 /**
338 * Provides the classes necessary to create an
339 * applet and the classes an applet uses
340 * to communicate with its applet context.
341 * <p>
342 * The applet framework involves two entities:
343 * the applet and the applet context.
344 * An applet is an embeddable window (see the
345 * {@link java.awt.Panel} class) with a few extra
346 * methods that the applet context can use to
347 * initialize, start, and stop the applet.
348 *
349 * @since 1.0
350 * @see java.awt
351 */
352 package java.lang.applet;
353 Note that while the comment separators /** and /* must be present, the
355 leading asterisks on the intermediate lines can be omitted.
356 package.html - This file can contain a package comment of the following
358 structure -- the comment is placed in the <body> element:
359 File: java/applet/package.html
361 <HTML>
362 <BODY>
363 Provides the classes necessary to create an applet and the
364 classes an applet uses to communicate with its applet context.
365 <p>
366 The applet framework involves two entities: the applet
367 and the applet context. An applet is an embeddable
368 window (see the {@link java.awt.Panel} class) with a
369 few extra methods that the applet context can use to
370 initialize, start, and stop the applet.
371 @since 1.0
373 @see java.awt
374 </BODY>
375 </HTML>
376 Notice this is just a normal HTML file and does not include a package
378 declaration. The content of the package comment file is written in
379 HTML, like all other comments, with one exception: The documentation
380 comment should not include the comment separators /** and */ or leading
381 asterisks. When writing the comment, you should make the first sentence
382 a summary about the package, and not put a title or any other text
383 between <body> and the first sentence. You can include package tags; as
384 with any documentation comment, all block tags must appear after the
385 main description. If you add a @see tag in a package comment file, it
386 must have a fully-qualified name. For more details, see the example of
387 package.html @
388 http://www.oracle.com/technetwork/java/javase/documenta‐
389 tion/index-137868.html#packagecomments.
390 Processing of package comment file - When the Javadoc tool runs, it
392 will automatically look for the package comment file; if found, the
393 Javadoc tool does the following:
394 o Copies the comment for processing. (For package.html, copies all
396 content between <body> and </body> HTML tags. You can include a
397 <head> section to put a <title>, source file copyright statement,
398 or other information, but none of these will appear in the gener‐
399 ated documentation.)
400 o Processes any package tags that are present.
402 o Inserts the processed text at the bottom of the package summary
404 page it generates, as shown in Package Summary @
405 http://docs.oracle.com/javase/7/docs/api/java/applet/package-sum‐
406 mary.html.
407 o Copies the first sentence of the package comment to the top of the
409 package summary page. It also adds the package name and this first
410 sentence to the list of packages on the overview page, as shown in
411 Overview Summary @
412 http://docs.oracle.com/javase/7/docs/api/overview-summary.html.
413 The end-of-sentence is determined by the same rules used for the
414 end of the first sentence of class and member main descriptions.
415 Overview Comment File
417 Each application or set of packages that you are documenting can have
418 its own overview documentation comment, kept in its own "source" file,
419 that the Javadoc tool will merge into the overview page that it gener‐
420 ates. You typically include in this comment any documentation that
421 applies to the entire application or set of packages.
422 To create an overview comment file, you can name the file anything you
424 want, typically overview.html and place it anywhere, typically at the
425 top level of the source tree. For example, if the source files for the
426 java.applet package are contained in /home/user/src/java/applet direc‐
427 tory, you could create an overview comment file at /home/user/src/over‐
428 view.html.
429 Notice you can have multiple overview comment files for the same set of
431 source files, in case you want to run javadoc multiple times on differ‐
432 ent sets of packages. For example, you could run javadoc once with
433 -private for internal documentation and again without that option for
434 public documentation. In this case, you could describe the documenta‐
435 tion as public or internal in the first sentence of each overview com‐
436 ment file.
437 The content of the overview comment file is one big documentation com‐
439 ment, written in HTML, like the package comment file described previ‐
440 ously. See that description for details. To re-iterate, when writing
441 the comment, you should make the first sentence a summary about the
442 application or set of packages, and not put a title or any other text
443 between <body> and the first sentence. You can include overview tags;
444 as with any documentation comment, all tags except in-line tags, such
445 as {@link}, must appear after the main description. If you add a @see
446 tag, it must have a fully-qualified name.
447 When you run the Javadoc tool, you specify the overview comment file
449 name with the -overview option. The file is then processed similar to
450 that of a package comment file.
451 o Copies all content between <body> and </body> tags for processing.
453 o Processes any overview tags that are present.
455 o Inserts the processed text at the bottom of the overview page it
457 generates, as shown in Overview Summary @
458 http://docs.oracle.com/javase/7/docs/api/overview-summary.html.
459 o Copies the first sentence of the overview comment to the top of
461 the overview summary page.
462 Miscellaneous Unprocessed Files
464 You can also include in your source any miscellaneous files that you
465 want the Javadoc tool to copy to the destination directory. These typi‐
466 cally includes graphic files, example Java source (.java) and class
467 (.class) files, and self-standing HTML files whose content would over‐
468 whelm the documentation comment of a normal Java source file.
469 To include unprocessed files, put them in a directory called doc-files
471 which can be a subdirectory of any package directory that contains
472 source files. You can have one such subdirectory for each package. You
473 might include images, example code, source files, .class files, applets
474 and HTML files. For example, if you want to include the image of a but‐
475 ton button.gif in the java.awt.Button class documentation, you place
476 that file in the /home/user/src/java/awt/doc-files/ directory. Notice
477 the doc-files directory should not be located at
478 /home/user/src/java/doc-files because java is not a package -- that is,
479 it does not directly contain any source files.
480 All links to these unprocessed files must be hard-coded, because the
482 Javadoc tool does not look at the files -- it simply copies the direc‐
483 tory and all its contents to the destination. For example, the link in
484 the Button.java doc comment might look like:
485 /**
486 * This button looks like this:
487 * <img src="doc-files/Button.gif">
488 */
489 Test Files and Template Files
491 Some developers have indicated they want to store test files and tem‐
492 plates files in the source tree near their corresponding source files.
493 That is, they would like to put them in the same directory, or a subdi‐
494 rectory, of those source files.
495 If you run the Javadoc tool by explicitly passing in individual source
497 filenames, you can deliberately omit test and templates files and pre‐
498 vent them from being processed. However, if you are passing in package
499 names or wildcards, you need to follow certain rules to ensure these
500 test files and templates files are not processed.
501 Test files differ from template files in that the former are legal,
503 compilable source files, while the latter are not, but may end with
504 ".java".
505 Test files - Often developers want to put compilable, runnable test
507 files for a given package in the same directory as the source files for
508 that package. But they want the test files to belong to a package other
509 than the source file package, such as the unnamed package (so the test
510 files have no package statement or a different package statement from
511 the source). In this scenario, when the source is being documented by
512 specifying its package name specified on the command line, the test
513 files will cause warnings or errors. You need to put such test files in
514 a subdirectory. For example, if you want to add test files for source
515 files in com.package1, put them in a subdirectory that would be an
516 invalid package name (because it contains a hyphen):
517 com/package1/test-files/
518 The test directory will be skipped by the Javadoc tool with no warn‐
520 ings.
521 If your test files contain doc comments, you can set up a separate run
523 of the Javadoc tool to produce documentation of the test files by pass‐
524 ing in their test source filenames with wildcards, such as com/pack‐
525 age1/test-files/*.java.
526 Templates for source files - Template files have names that often end
528 in ".java" and are not compilable. If you have a template for a source
529 file that you want to keep in the source directory, you can name it
530 with a dash (such as Buffer-Template.java), or any other illegal Java
531 character, to prevent it from being processed. This relies on the fact
532 that the Javadoc tool will only process source files whose name, when
533 stripped of the ".java" suffix, is actually a legal class name (see
534 information about Identifiers in the Java Language Specification).
535
537 By default, javadoc uses a standard doclet that generates HTML-format‐
538 ted documentation. This doclet generates the following kinds of files
539 (where each HTML "page" corresponds to a separate file). Note that
540 javadoc generates files with two types of names: those named after
541 classes/interfaces, and those that are not (such as package-sum‐
542 mary.html). Files in the latter group contain hyphens to prevent file‐
543 name conflicts with those in the former group.
544 Basic Content Pages
546 o One class or interface page (classname.html) for each class or
548 interface it is documenting.
549 o One package page (package-summary.html) for each package it is
551 documenting. The Javadoc tool will include any HTML text provided
552 in a file named package.html or package-info.java in the package
553 directory of the source tree.
554 o One overview page (overview-summary.html) for the entire set of
556 packages. This is the front page of the generated document. The
557 Javadoc tool will include any HTML text provided in a file speci‐
558 fied with the -overview option. Note that this file is created
559 only if you pass into javadoc two or more package names. For fur‐
560 ther explanation, see HTML Frames.)
561 Cross-Reference Pages
563 o One class hierarchy page for the entire set of packages (over‐
565 view-tree.html). To view this, click on "Overview" in the naviga‐
566 tion bar, then click on "Tree".
567 o One class hierarchy page for each package (package-tree.html) To
569 view this, go to a particular package, class or interface page;
570 click "Tree" to display the hierarchy for that package.
571 o One "use" page for each package (package-use.html) and a separate
573 one for each class and interface (class-use/classname.html). This
574 page describes what packages, classes, methods, constructors and
575 fields use any part of the given class, interface or package.
576 Given a class or interface A, its "use" page includes subclasses
577 of A, fields declared as A, methods that return A, and methods and
578 constructors with parameters of type A. You can access this page
579 by first going to the package, class or interface, then clicking
580 on the "Use" link in the navigation bar.
581 o A deprecated API page (deprecated-list.html) listing all depre‐
583 cated names. (A deprecated name is not recommended for use, gener‐
584 ally due to improvements, and a replacement name is usually given.
585 Deprecated APIs may be removed in future implementations.)
586 o A constant field values page (constant-values.html) for the values
588 of static fields.
589 o A serialized form page (serialized-form.html) for information
591 about serializable and externalizable classes. Each such class has
592 a description of its serialization fields and methods. This infor‐
593 mation is of interest to re-implementors, not to developers using
594 the API. While there is no link in the navigation bar, you can get
595 to this information by going to any serialized class and clicking
596 "Serialized Form" in the "See also" section of the class comment.
597 The standard doclet automatically generates a serialized form
598 page: any class (public or non-public) that implements Serializ‐
599 able is included, along with readObject and writeObject methods,
600 the fields that are serialized, and the doc comments from the
601 @serial, @serialField, and @serialData tags. Public serializable
602 classes can be excluded by marking them (or their package) with
603 @serial exclude, and package-private serializable classes can be
604 included by marking them (or their package) with @serial include.
605 As of 1.4, you can generate the complete serialized form for pub‐
606 lic and private classes by running javadoc without specifying the
607 -private option.
608 o An index (index-*.html) of all class, interface, constructor,
610 field and method names, alphabetically arranged. This is interna‐
611 tionalized for Unicode and can be generated as a single file or as
612 a separate file for each starting character (such as A-Z for Eng‐
613 lish).
614 Support Files
616 o A help page (help-doc.html) that describes the navigation bar and
618 the above pages. You can provide your own custom help file to
619 override the default using -helpfile.
620 o One index.html file which creates the HTML frames for display.
622 This is the file you load to display the front page with frames.
623 This file itself contains no text content.
624 o Several frame files (*-frame.html) containing lists of packages,
626 classes and interfaces, used when HTML frames are being displayed.
627 o A package list file (package-list), used by the -link and -linkof‐
629 fline options. This is a text file, not HTML, and is not reachable
630 through any links.
631 o A style sheet file (stylesheet.css) that controls a limited amount
633 of color, font family, font size, font style and positioning on
634 the generated pages.
635 o A doc-files directory that holds any image, example, source code
637 or other files that you want copied to the destination directory.
638 These files are not processed by the Javadoc tool in any manner --
639 that is, any javadoc tags in them will be ignored. This directory
640 is not generated unless it exists in the source tree.
641 HTML Frames
643 The Javadoc tool will generate either two or three HTML frames, as
645 shown in the figure below. It creates the minimum necessary number of
646 frames by omitting the list of packages if there is only one package
647 (or no packages). That is, when you pass a single package name or
648 source files (*.java) belonging to a single package as arguments into
649 the javadoc command, it will create only one frame (C) in the left-hand
650 column -- the list of classes. When you pass into javadoc two or more
651 package names, it creates a third frame (P) listing all packages, as
652 well as an overview page (Detail). This overview page has the filename
653 overview-summary.html. Thus, this file is created only if you pass in
654 two or more package names. You can bypass frames by clicking on the "No
655 Frames" link or entering at overview-summary.html.
656 If you are unfamiliar with HTML frames, you should be aware that frames
658 can have focus for printing and scrolling. To give a frame focus, click
659 on it. Then on many browsers the arrow keys and page keys will scroll
660 that frame, and the print menu command will print it.
661 Load one of the following two files as the starting page depending on
663 whether you want HTML frames or not:
664 o index.html (for frames)
666 o overview-summary.html (for no frames)
668 Generated File Structure
670 The generated class and interface files are organized in the same
672 directory hierarchy that Java source files and class files are orga‐
673 nized. This structure is one directory per subpackage.
674 For example, the document generated for the class java.applet.Applet
676 class would be located at java/applet/Applet.html. The file structure
677 for the java.applet package follows, given that the destination direc‐
678 tory is named apidocs. All files that contain the word "frame" appear
679 in the upper-left or lower-left frames, as noted. All other HTML files
680 appear in the right-hand frame.
681 NOTE - Directories are shown in bold. The asterisks (*) indicate the
683 files and directories that are omitted when the arguments to javadoc
684 are source filenames (*.java) rather than package names. Also when
685 arguments are source filenames, package-list is created but is empty.
686 The doc-files directory will not be created in the destination unless
687 it exists in the source tree.
688 apidocs Top directory
690 index.html Initial page that sets up HTML frames
691 * overview-summary.html Lists all packages with first sentence summaries
692 overview-tree.html Lists class hierarchy for all packages
693 deprecated-list.html Lists deprecated API for all packages
694 constant-values.html Lists values of static fields for all packages
695 serialized-form.html Lists serialized form for all packages
696 * overview-frame.html Lists all packages, used in upper-left frame
697 allclasses-frame.html Lists all classes for all packages, used in lower-left frame
698 help-doc.html Lists user help for how these pages are organized
699 index-all.html Default index created without -splitindex option
700 index-files Directory created with -splitindex option
701 index-<number>.html Index files created with -splitindex option
702 package-list Lists package names, used only for resolving external refs
703 stylesheet.css HTML style sheet for defining fonts, colors and positions
704 java Package directory
705 applet Subpackage directory
706 Applet.html Page for Applet class
707 AppletContext.html Page for AppletContext interface
708 AppletStub.html Page for AppletStub interface
709 AudioClip.html Page for AudioClip interface
710 * package-summary.html Lists classes with first sentence summaries for this package
711 * package-frame.html Lists classes in this package, used in lower left-hand frame
712 * package-tree.html Lists class hierarchy for this package
713 package-use Lists where this package is used
714 doc-files Directory holding image and example files
715 class-use Directory holding pages API is used
716 Applet.html Page for uses of Applet class
717 AppletContext.html Page for uses of AppletContext interface
718 AppletStub.html Page for uses of AppletStub interface
719 AudioClip.html Page for uses of AudioClip interface
720 src-html Source code directory
721 java Package directory
722 applet Subpackage directory
723 Applet.html Page for Applet source code
724 AppletContext.html Page for AppletContext source code
725 AppletStub.html Page for AppletStub source code
726 AudioClip.html Page for AudioClip source code
727 Generated API Declarations
729 The Javadoc tool generates a declaration at the start of each class,
730 interface, field, constructor, and method description for that API
731 item. For example, the declaration for the Boolean class is:
732 public final class Boolean
734 extends Object
735 implements Serializable
736 and the declaration for the Boolean.valueOfmethod is:
738 public static Boolean valueOf(String s)
740 The Javadoc tool can include the modifiers public, protected, private,
742 abstract, final, static, transient, and volatile, but not synchronized
743 or native. These last two modifiers are considered implementation
744 detail and not part of the API specification.
745 Rather than relying on the keyword synchronized, APIs should document
747 their concurrency semantics in the comment's main description, as in "a
748 single Enumeration cannot be used by multiple threads concurrently".
749 The document should not describe how to achieve these semantics. As
750 another example, while Hashtable should be thread-safe, there's no rea‐
751 son to specify that we achieve this by synchronizing all of its
752 exported methods. We should reserve the right to synchronize internally
753 at the bucket level, thus offering higher concurrency.
754
756 The original "Documentation Comment Specification" can be found under
757 related documentation.
758 Commenting the Source Code
760 You can include documentation comments ("doc comments") in the source
761 code, ahead of declarations for any class, interface, method, construc‐
762 tor, or field. You can also create doc comments for each package and
763 another one for the overview, though their syntax is slightly differ‐
764 ent. Doc comments are also known informally as "Javadoc comments" (but
765 this term violates its trademark usage). A doc comment consists of the
766 characters between the characters /** that begin the comment and the
767 characters */ that end it. Leading asterisks are allowed on each line
768 and are described further below. The text in a comment can continue
769 onto multiple lines.
770 /**
771 * This is the typical format of a simple documentation comment
772 * that spans two lines.
773 */
774 To save space you can put a comment on one line:
776 /** This comment takes up only one line. */
777 Placement of comments - Documentation comments are recognized only when
779 placed immediately before class, interface, constructor, method, or
780 field declarations -- see the class example, method example, and field
781 example. Documentation comments placed in the body of a method are
782 ignored. Only one documentation comment per declaration statement is
783 recognized by the Javadoc tool.
784 A common mistake is to put an import statement between the class com‐
786 ment and the class declaration. Avoid this, as the Javadoc tool will
787 ignore the class comment.
788 /**
789 * This is the class comment for the class Whatever.
790 */
791 import com.sun; // MISTAKE - Important not to put import statement here
793 public class Whatever {
795 }
796 A doc comment is composed of a main description followed by a tag sec‐
798 tion - The main description begins after the starting delimiter /** and
799 continues until the tag section. The tag section starts with the first
800 block tag, which is defined by the first @ character that begins a line
801 (ignoring leading asterisks, white space, and leading separator /**).
802 It is possible to have a comment with only a tag section and no main
803 description. The main description cannot continue after the tag section
804 begins. The argument to a tag can span multiple lines. There can be any
805 number of tags -- some types of tags can be repeated while others can‐
806 not. For example, this @see starts the tag section:
807 /**
808 * This sentence would hold the main description for this doc comment.
809 * @see java.lang.Object
810 */
811 Block tags and in-line tags - A tag is a special keyword within a doc
813 comment that the Javadoc tool can process. There are two kinds of tags:
814 block tags, which appear as @tag (also known as "standalone tags"), and
815 in-line tags, which appear within curly braces, as {@tag}. To be inter‐
816 preted, a block tag must appear at the beginning of a line, ignoring
817 leading asterisks, white space, and separator (/**). This means you can
818 use the @ character elsewhere in the text and it will not be inter‐
819 preted as the start of a tag. If you want to start a line with the @
820 character and not have it be interpreted, use the HTML entity @.
821 Each block tag has associated text, which includes any text following
822 the tag up to, but not including, either the next tag, or the end of
823 the doc comment. This associated text can span multiple lines. An
824 in-line tag is allowed and interpreted anywhere that text is allowed.
825 The following example contains the block tag @deprecated and in-line
826 tag {@link}.
827 /**
828 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
829 */
830 Comments are written in HTML - The text must be written in HTML, in
832 that they should use HTML entities and can use HTML tags. You can use
833 whichever version of HTML your browser supports; we have written the
834 standard doclet to generate HTML 3.2-compliant code elsewhere (outside
835 of the documentation comments) with the inclusion of cascading style
836 sheets and frames. (We preface each generated file with "HTML 4.0"
837 because of the frame sets.)
838 For example, entities for the less-than (<) and greater-than (>) sym‐
840 bols should be written < and >. Likewise, the ampersand (&) should be
841 written &. The bold HTML tag <b> is shown in the following example.
842 Here is a doc comment:
844 /**
845 * This is a <b>doc</b> comment.
846 * @see java.lang.Object
847 */
848 Leading asterisks - When javadoc parses a doc comment, leading asterisk
850 (*) characters on each line are discarded; blanks and tabs preceding
851 the initial asterisk (*) characters are also discarded. Starting with
852 1.4, if you omit the leading asterisk on a line, the leading white
853 space is no longer removed. This enables you to paste code examples
854 directly into a doc comment inside a <PRE> tag, and its indentation
855 will be honored. Spaces are generally interpreted by browsers more uni‐
856 formly than tabs. Indentation is relative to the left margin (rather
857 than the separator /** or <PRE> tag).
858 First sentence - The first sentence of each doc comment should be a
860 summary sentence, containing a concise but complete description of the
861 declared entity. This sentence ends at the first period that is fol‐
862 lowed by a blank, tab, or line terminator, or at the first block tag.
863 The Javadoc tool copies this first sentence to the member summary at
864 the top of the HTML page.
865 Declaration with multiple fields - Java allows declaring multiple
867 fields in a single statement, but this statement can have only one doc‐
868 umentation comment, which is copied for all fields. Therefore if you
869 want individual documentation comments for each field, you must declare
870 each field in a separate statement. For example, the following documen‐
871 tation comment doesn't make sense written as a single declaration and
872 would be better handled as two declarations:
873 /**
874 * The horizontal and vertical distances of point (x,y)
875 */
876 public int x, y; // Avoid this
877 The Javadoc tool generates the following documentation from the above
879 code:
880 public int x
881 The horizontal and vertical distances of point (x,y)
882 public int y
883 The horizontal and vertical distances of point (x,y)
884 Use header tags carefully - When writing documentation comments for
886 members, it's best not to use HTML heading tags such as <H1> and <H2>,
887 because the Javadoc tool creates an entire structured document and
888 these structural tags might interfere with the formatting of the gener‐
889 ated document. However, it is fine to use these headings in class and
890 package comments to provide your own structure.
891 Automatic Copying of Method Comments
893 The Javadoc tool has the ability to copy or "inherit" method comments
894 in classes and interfaces under the following two circumstances. Con‐
895 structors, fields and nested classes do not inherit doc comments.
896 o Automatically inherit comment to fill in missing text - When a
898 main description, or @return, @param or @throws tag is missing
899 from a method comment, the Javadoc tool copies the corresponding
900 main description or tag comment from the method it overrides or
901 implements (if any), according to the algorithm below.
902 More specifically, when a @param tag for a particular parameter is
904 missing, then the comment for that parameter is copied from the
905 method further up the inheritance hierarchy. When a @throws tag for
906 a particular exception is missing, the @throws tag is copied only if
907 that exception is declared.
908 This behavior contrasts with version 1.3 and earlier, where the
910 presence of any main description or tag would prevent all comments
911 from being inherited.
912 o Explicitly inherit comment with {@inheritDoc} tag - Insert the
914 inline tag {@inheritDoc} in a method main description or @return,
915 @param or @throws tag comment -- the corresponding inherited main
916 description or tag comment is copied into that spot.
917 The source file for the inherited method need only be on the path spec‐
919 ified by -sourcepath for the doc comment to actually be available to
920 copy. Neither the class nor its package needs to be passed in on the
921 command line. This contrasts with 1.3.x and earlier releases, where the
922 class had to be a documented class
923 Inherit from classes and interfaces - Inheriting of comments occurs in
925 all three possible cases of inheritance from classes and interfaces:
926 o When a method in a class overrides a method in a superclass
928 o When a method in an interface overrides a method in a superinter‐
930 face
931 o When a method in a class implements a method in an interface
933 In the first two cases, for method overrides, the Javadoc tool gener‐
935 ates a subheading "Overrides" in the documentation for the overriding
936 method, with a link to the method it is overriding, whether or not the
937 comment is inherited.
938 In the third case, when a method in a given class implements a method
940 in an interface, the Javadoc tool generates a subheading "Specified by"
941 in the documentation for the overriding method, with a link to the
942 method it is implementing. This happens whether or not the comment is
943 inherited.
944 Algorithm for Inheriting Method Comments - If a method does not have a
946 doc comment, or has an {@inheritDoc} tag, the Javadoc tool searches for
947 an applicable comment using the following algorithm, which is designed
948 to find the most specific applicable doc comment, giving preference to
949 interfaces over superclasses:
950 1. Look in each directly implemented (or extended) interface in the
952 order they appear following the word implements (or extends) in
953 the method declaration. Use the first doc comment found for this
954 method.
955 2. If step 1 failed to find a doc comment, recursively apply this
957 entire algorithm to each directly implemented (or extended)
958 interface, in the same order they were examined in step 1.
959 3. If step 2 failed to find a doc comment and this is a class other
961 than Object (not an interface):
962 a. If the superclass has a doc comment for this method, use it.
964 b. If step 3a failed to find a doc comment, recursively apply
966 this entire algorithm to the superclass.
967
969 The Javadoc tool parses special tags when they are embedded within a
970 Java doc comment. These doc tags enable you to autogenerate a complete,
971 well-formatted API from your source code. The tags start with an "at"
972 sign (@) and are case-sensitive -- they must be typed with the upper‐
973 case and lowercase letters as shown. A tag must start at the beginning
974 of a line (after any leading spaces and an optional asterisk) or it is
975 treated as normal text. By convention, tags with the same name are
976 grouped together. For example, put all @see tags together.
977 Tags come in two types:
979 o Block tags - Can be placed only in the tag section that follows
981 the main description. Block tags are of the form: @tag.
982 o Inline tags - Can be placed anywhere in the main description or in
984 the comments for block tags. Inline tags are denoted by curly
985 braces: {@tag}.
986 For information about tags we might introduce in future releases, see
988 Proposed Tags @
989 http://java.sun.com/j2se/javadoc/proposed-tags.html.
990 The current tags are:
992 For custom tags, see the -tag option.
994 @author name-text
996 Adds an "Author" entry with the specified name-text to the gener‐
997 ated docs when the -author option is used. A doc comment may con‐
998 tain multiple @author tags. You can specify one name per @author
999 tag or multiple names per tag. In the former case, the Javadoc
1000 tool inserts a comma (,) and space between names. In the latter
1001 case, the entire text is simply copied to the generated document
1002 without being parsed. Therefore, you can use multiple names per
1003 line if you want a localized name separator other than comma.
1004 For more details, see Where Tags Can Be Used and writing @author tags @
1006 http://www.oracle.com/technetwork/java/javase/documenta‐
1007 tion/index-137868.html#@author.
1008 @deprecated deprecated-text Note: You can deprecate a program ele‐
1010 ment using the @Deprecated annotation.
1011 Adds a comment indicating that this API should no longer be used (even
1013 though it may continue to work). The Javadoc tool moves the depre‐
1014 cated-text ahead of the main description, placing it in italics and
1015 preceding it with a bold warning: "Deprecated". This tag is valid in
1016 all doc comments: overview, package, class, interface, constructor,
1017 method and field.
1018 The first sentence of deprecated-text should at least tell the user
1020 when the API was deprecated and what to use as a replacement. The
1021 Javadoc tool copies just the first sentence to the summary section and
1022 index. Subsequent sentences can also explain why it has been depre‐
1023 cated. You should include a {@link} tag (for Javadoc 1.2 or later) that
1024 points to the replacement API:
1025 For more details, see writing @deprecated tags @
1027 http://www.oracle.com/technetwork/java/javase/documenta‐
1028 tion/index-137868.html#@deprecated.
1029 o For Javadoc 1.2 and later, use a {@link} tag. This creates the
1031 link in-line, where you want it. For example:
1032 /**
1033 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
1034 */
1035 o For Javadoc 1.1, the standard format is to create a @see tag
1038 (which cannot be in-line) for each @deprecated tag.
1039 For more about deprecation, see The @deprecated tag @
1041 http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/depreca‐
1042 tion/index.html.
1043 {@code text}
1045 Equivalent to <code>{@literal}</code>.
1046 Displays text in code font without interpreting the text as HTML
1048 markup or nested javadoc tags. This enables you to use regular angle
1049 brackets (< and >) instead of the HTML entities (< and >) in doc
1050 comments, such as in parameter types (<Object>), inequalities (3 <
1051 4), or arrows (<-). For example, the doc comment text:
1052 {@code A<B>C}
1053 displays in the generated HTML page unchanged, as:
1056 A<B>C
1057 The noteworthy point is that the <B> is not interpreted as bold and
1060 is in code font.
1061 If you want the same functionality without the code font, use {@lit‐
1063 eral}.
1064 {@docRoot}
1066 Represents the relative path to the generated document's (desti‐
1067 nation) root directory from any generated page. It is useful when
1068 you want to include a file, such as a copyright page or company
1069 logo, that you want to reference from all generated pages. Link‐
1070 ing to the copyright page from the bottom of each page is common.
1071 This {@docRoot} tag can be used both on the command line and in a
1073 doc comment: This tag is valid in all doc comments: overview, pack‐
1074 age, class, interface, constructor, method and field, including the
1075 text portion of any tag (such as @return, @param and @deprecated).
1076 1. On the command line, where the header/footer/bottom are
1078 defined:
1079 javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
1080 NOTE - When using {@docRoot} this way in a make file, some make‐
1083 file programs require special escaping for the brace {} charac‐
1084 ters. For example, the Inprise MAKE version 5.2 running on Win‐
1085 dows requires double braces: {{@docRoot}}. It also requires dou‐
1086 ble (rather than single) quotes to enclose arguments to options
1087 such as -bottom (with the quotes around the href argument omit‐
1088 ted).
1089 2. In a doc comment:
1091 /**
1092 * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
1093 */
1094 The reason this tag is needed is because the generated docs are in
1097 hierarchical directories, as deep as the number of subpackages. This
1098 expression:
1099 <a href="{@docRoot}/copyright.html">
1100 would resolve to:
1103 <a href="../../copyright.html"> for java/lang/Object.java
1104 and
1107 <a href="../../../copyright.html"> for java/lang/ref/Reference.java
1108 @exception class-name description
1111 The @exception tag is a synonym for @throws.
1112 {@inheritDoc}
1114 Inherits (copies) documentation from the "nearest" inheritable
1115 class or implementable interface into the current doc comment at
1116 this tag's location. This allows you to write more general com‐
1117 ments higher up the inheritance tree, and to write around the
1118 copied text.
1119 This tag is valid only in these places in a doc comment:
1121 o In the main description block of a method. In this case, the
1123 main description is copied from a class or interface up the
1124 hierarchy.
1125 o In the text arguments of the @return, @param and @throws tags
1127 of a method. In this case, the tag text is copied from the cor‐
1128 responding tag up the hierarchy.
1129 See Automatic Copying of Method Comments for a more precise descrip‐
1131 tion of how comments are found in the inheritance hierarchy. Note
1132 that if this tag is missing, the comment is or is not automatically
1133 inherited according to rules described in that section.
1134 {@link package.class#member label}
1136 Inserts an in-line link with visible text label that points to
1137 the documentation for the specified package, class or member name
1138 of a referenced class. This tag is valid in all doc comments:
1139 overview, package, class, interface, constructor, method and
1140 field, including the text portion of any tag (such as @return,
1141 @param and @deprecated).
1142 This tag is very simliar to @see -- both require the same references
1144 and accept exactly the same syntax for package.class#member and
1145 label. The main difference is that {@link} generates an in-line link
1146 rather than placing the link in the "See Also" section. Also, the
1147 {@link} tag begins and ends with curly braces to separate it from
1148 the rest of the in-line text. If you need to use "}" inside the
1149 label, use the HTML entity notation }
1150 There is no limit to the number of {@link} tags allowed in a sen‐
1152 tence. You can use this tag in the main description part of any doc‐
1153 umentation comment or in the text portion of any tag (such as @dep‐
1154 recated, @return or @param).
1155 For example, here is a comment that refers to the getComponen‐
1157 tAt(int, int) method:
1158 Use the {@link #getComponentAt(int, int) getComponentAt} method.
1159 From this, the standard doclet would generate the following HTML
1162 (assuming it refers to another class in the same package):
1163 Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
1164 Which appears on the web page as:
1167 Use the getComponentAt method.
1168 You can extend {@link} to link to classes not being documented by
1171 using the -link option.
1172 For more details, see writing {@link} tags @
1174 http://www.oracle.com/technetwork/java/javase/documenta‐
1175 tion/index-137868.html#{@link}.
1176 {@linkplain package.class#member label}
1178 Identical to {@link}, except the link's label is displayed in
1179 plain text than code font. Useful when the label is plain text.
1180 Example:
1181 Refer to {@linkplain add() the overridden method}.
1182 This would display as:
1185 Refer to the overridden method.
1187 {@literal text}
1189 Displays text without interpreting the text as HTML markup or
1190 nested javadoc tags. This enables you to use regular angle brack‐
1191 ets (< and >) instead of the HTML entities (< and >) in doc com‐
1192 ments, such as in parameter types (<Object>), inequalities (3 <
1193 4), or arrows (<-). For example, the doc comment text:
1194 {@literal A<B>C}
1195 displays unchanged in the generated HTML page in your browser, as:
1198 A<B>C
1200 The noteworthy point is that the <B> is not interpreted as bold (and
1202 it is not in code font).
1203 If you want the same functionality but with the text in code font,
1205 use {@code}.
1206 @param parameter-name description
1208 Adds a parameter with the specified parameter-name followed by
1209 the specified description to the "Parameters" section. When writ‐
1210 ing the doc comment, you may continue the description onto multi‐
1211 ple lines. This tag is valid only in a doc comment for a method,
1212 constructor or class.
1213 The parameter-name can be the name of a parameter in a method or
1215 constructor, or the name of a type parameter of a class, method or
1216 constructor. Use angle brackets around this parameter name to spec‐
1217 ify the use of a type parameter.
1218 Example of a type parameter of a class:
1220 /**
1221 * @param <E> Type of element stored in a list
1222 */
1223 public interface List<E> extends Collection<E> {
1224 }
1225 Example of a type parameter of a method:
1228 /**
1229 * @param string the string to be converted
1230 * @param type the type to convert the string to
1231 * @param <T> the type of the element
1232 * @param <V> the value of the element
1233 */
1234 <T, V extends T> V convert(String string, Class<T> type) {
1235 }
1236 For more details, see writing @param tags @
1239 http://www.oracle.com/technetwork/java/javase/documenta‐
1240 tion/index-137868.html#@param.
1241 @return description
1243 Adds a "Returns" section with the description text. This text
1244 should describe the return type and permissible range of values.
1245 This tag is valid only in a doc comment for a method.
1246 For more details, see writing @return tags @
1248 http://www.oracle.com/technetwork/java/javase/documenta‐
1249 tion/index-137868.html#@return.
1250 @see reference
1252 Adds a "See Also" heading with a link or text entry that points
1253 to reference. A doc comment may contain any number of @see tags,
1254 which are all grouped under the same heading. The @see tag has
1255 three variations; the third form below is the most common. This
1256 tag is valid in any doc comment: overview, package, class, inter‐
1257 face, constructor, method or field. For inserting an in-line link
1258 within a sentence to a package, class or member, see {@link}.
1259 @see "string"
1261 Adds a text entry for string. No link is generated. The string
1262 is a book or other reference to information not available by
1263 URL. The Javadoc tool distinguishes this from the previous
1264 cases by looking for a double-quote (") as the first charac‐
1265 ter. For example:
1266 @see "The Java Programming Language"
1267 This generates text such as:
1270 See Also:
1272 "The Java Programming Language"
1273 @see <a href="URL#value">label</a>
1275 Adds a link as defined by URL#value. The URL#value is a rela‐
1276 tive or absolute URL. The Javadoc tool distinguishes this from
1277 other cases by looking for a less-than symbol (<) as the first
1278 character. For example:
1279 @see <a href="spec.html#section">Java Spec</a>
1280 This generates a link such as:
1281 See Also:
1283 Java Spec
1284 @see package.class#member label
1286 Adds a link, with visible text label, that points to the docu‐
1287 mentation for the specified name in the Java Language that is
1288 referenced. The label is optional; if omitted, the name
1289 appears instead as the visible text, suitably shortened -- see
1290 How a name is displayed. Use -noqualifier to globally remove
1291 the package name from this visible text. Use the label when
1292 you want the visible text to be different from the auto-gener‐
1293 ated visible text.
1294 Only in version 1.2, just the name but not the label would auto‐
1296 matically appear in <code> HTML tags, Starting with 1.2.2, the
1297 <code> is always included around the visible text, whether or not
1298 a label is used.
1299 o package.class#member is any valid program element name that
1301 is referenced -- a package, class, interface, constructor,
1302 method or field name -- except that the character ahead of
1303 the member name should be a hash character (#). The class
1304 represents any top-level or nested class or interface. The
1305 member represents any constructor, method or field (not a
1306 nested class or interface). If this name is in the docu‐
1307 mented classes, the Javadoc tool will automatically create a
1308 link to it. To create links to external referenced classes,
1309 use the -link option. Use either of the other two @see forms
1310 for referring to documentation of a name that does not
1311 belong to a referenced class. This argument is described at
1312 greater length below under Specifying a Name.
1313 o label is optional text that is visible as the link's label.
1315 The label can contain whitespace. If label is omitted, then
1316 package.class.member will appear, suitably shortened rela‐
1317 tive to the current class and package -- see How a name is
1318 displayed.
1319 o A space is the delimiter between package.class#member and
1321 label. A space inside parentheses does not indicate the
1322 start of a label, so spaces may be used between parameters
1323 in a method.
1324 Example - In this example, an @see tag (in the Character class)
1326 refers to the equals method in the String class. The tag includes
1327 both arguments: the name "String#equals(Object)" and the label
1328 "equals".
1329 /**
1330 * @see String#equals(Object) equals
1331 */
1332 The standard doclet produces HTML something like this:
1333 <dl>
1334 <dt><b>See Also:</b>
1335 <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
1336 </dl>
1337 Which looks something like this in a browser, where the label is
1338 the visible link text:
1339 See Also:
1341 equals
1342 Specifying a name - This package.class#member name can be either
1344 fully-qualified, such as java.lang.String#toUpperCase() or not,
1345 such as String#toUpperCase() or #toUpperCase(). If less than
1346 fully-qualified, the Javadoc tool uses the normal Java compiler
1347 search order to find it, further described below in Search order
1348 for @see. The name can contain whitespace within parentheses,
1349 such as between method arguments.
1350 Of course the advantage of providing shorter, "partially-quali‐
1352 fied" names is that they are shorter to type and there is less
1353 clutter in the source code. The following table shows the differ‐
1354 ent forms of the name, where Class can be a class or interface,
1355 Type can be a class, interface, array, or primitive, and method
1356 can be a method or constructor.
1357 The following notes apply to the above table:
1359 o The first set of forms (with no class or package) will cause
1361 the Javadoc tool to search only through the current class's
1362 hierarchy. It will find a member of the current class or
1363 interface, one of its superclasses or superinterfaces, or
1364 one of its enclosing classes or interfaces (search steps
1365 1-3). It will not search the rest of the current package or
1366 other packages (search steps 4-5).
1367 o If any method or constructor is entered as a name with no
1369 parentheses, such as getValue, and if there is no field with
1370 the same name, the Javadoc tool will correctly create a link
1371 to it, but will print a warning message reminding you to add
1372 the parentheses and arguments. If this method is overloaded,
1373 the Javadoc tool will link to the first method its search
1374 encounters, which is unspecified.
1375 o Nested classes must be specified as outer.inner, not simply
1377 inner, for all forms.
1378 o As stated, the hash character (#), rather than a dot (.)
1380 separates a member from its class. This enables the Javadoc
1381 tool to resolve ambiguities, since the dot also separates
1382 classes, nested classes, packages, and subpackages. However,
1383 the Javadoc tool is generally lenient and will properly
1384 parse a dot if you know there is no ambiguity, though it
1385 will print a warning.
1386 Search order for @see - the Javadoc tool will process a @see tag
1388 that appears in a source file (.java), package file (package.html
1389 or package-info.java) or overview file (overview.html). In the
1390 latter two files, you must fully-qualify the name you supply with
1391 @see. In a source file, you can specify a name that is
1392 fully-qualified or partially-qualified.
1393 When the Javadoc tool encounters a @see tag in a .java file that
1395 is not fully qualified, it searches for the specified name in the
1396 same order as the Java compiler would (except the Javadoc tool
1397 will not detect certain namespace ambiguities, since it assumes
1398 the source code is free of these errors). This search order is
1399 formally defined in the Java Language Specification. The Javadoc
1400 tool searches for that name through all related and imported
1401 classes and packages. In particular, it searches in this order:
1402 1. the current class or interface
1404 2. any enclosing classes and interfaces, searching closest
1406 first
1407 3. any superclasses and superinterfaces, searching closest
1409 first
1410 4. the current package
1412 5. any imported packages, classes and interfaces, searching in
1414 the order of the import statement
1415 The Javadoc tool continues to search recursively through steps
1417 1-3 for each class it encounters until it finds a match. That is,
1418 after it searches through the current class and its enclosing
1419 class E, it will search through E's superclasses before E's
1420 enclosing classes. In steps 4 and 5, the Javadoc tool does not
1421 search classes or interfaces within a package in any specified
1422 order (that order depends on the particular compiler). In step 5,
1423 the Javadoc tool looks in java.lang, since that is automatically
1424 imported by all programs.
1425 The Javadoc tool does not necessarily look in subclasses, nor
1427 will it look in other packages even if their documentation is
1428 being generated in the same run. For example, if the @see tag is
1429 in the java.awt.event.KeyEvent class and refers to a name in the
1430 java.awt package, javadoc does not look in that package unless
1431 that class imports it.
1432 How a name is displayed - If label is omitted, then pack‐
1434 age.class.member appears. In general, it is suitably shortened
1435 relative to the current class and package. By "shortened", we
1436 mean the Javadoc tool displays only the minimum name necessary.
1437 For example, if the String.toUpperCase() method contains refer‐
1438 ences to a member of the same class and to a member of a differ‐
1439 ent class, the class name is displayed only in the latter case,
1440 as shown in the following table.
1441 Use -noqualifier to globally remove the package names.
1443 Examples of @see
1445 The comment to the right shows how the name would be displayed if
1446 the @see tag is in a class in another package, such as
1447 java.applet.Applet.
1448 See also:
1449 @see java.lang.String // String
1450 @see java.lang.String The String class // The String class
1451 @see String // String
1452 @see String#equals(Object) // String.equals(Object)
1453 @see String#equals // String.equals(java.lang.Object)
1454 @see java.lang.Object#wait(long) // java.lang.Object.wait(long)
1455 @see Character#MAX_RADIX // Character.MAX_RADIX
1456 @see <a href="spec.html">Java Spec</a> // Java Spec
1457 @see "The Java Programming Language" // "The Java Programming Language"
1458 You can extend @see to link to classes not being documented by
1459 using the -link option.
1460 For more details, see writing @see tags @
1462 http://www.oracle.com/technetwork/java/javase/documenta‐
1463 tion/index-137868.html#@see.
1464 @serial field-description | include | exclude
1466 Used in the doc comment for a default serializable field.
1467 An optional field-description should explain the meaning of the
1469 field and list the acceptable values. If needed, the description can
1470 span multiple lines. The standard doclet adds this information to
1471 the serialized form page.
1472 If a serializable field was added to a class some time after the
1474 class was made serializable, a statement should be added to its main
1475 description to identify at which version it was added.
1476 The include and exclude arguments identify whether a class or pack‐
1478 age should be included or excluded from the serialized form page.
1479 They work as follows:
1480 o A public or protected class that implements Serializable is
1482 included unless that class (or its package) is marked @serial
1483 exclude.
1484 o A private or package-private class that implements Serializable
1486 is excluded unless that class (or its package) is marked
1487 @serial include.
1488 Examples: The javax.swing package is marked @serial exclude (in
1490 package.html or package-info.java). The public class java.secu‐
1491 rity.BasicPermission is marked @serial exclude. The package-private
1492 class java.util.PropertyPermissionCollection is marked @serial
1493 include.
1494 The tag @serial at a class level overrides @serial at a package
1496 level.
1497 For more information about how to use these tags, along with an
1499 example, see " Documenting Serializable Fields and Data for a Class
1500 @
1501 http://docs.oracle.com/javase/7/docs/platform/serializa‐
1502 tion/spec/serial-arch.html," Section 1.6 of the Java Object Serial‐
1503 ization Specification. Also see the Serialization FAQ @
1504 http://java.sun.com/javase/technologies/core/basic/serialization‐
1505 FAQ.jsp#javadoc_warn_missing, which covers common questions, such as
1506 "Why do I see javadoc warnings stating that I am missing @serial
1507 tags for private fields if I am not running javadoc with the -pri‐
1508 vate switch?". Also see Sun's criteria @
1509 http://java.sun.com/j2se/javadoc/writingapispecs/serialized-crite‐
1510 ria.html for including classes in the serialized form specification.
1511 @serialField field-name field-type field-description
1513 Documents an ObjectStreamField component of a Serializable
1514 class's serialPersistentFields member. One @serialField tag
1515 should be used for each ObjectStreamField component.
1516 @serialData data-description
1518 The data-description documents the types and order of data in the
1519 serialized form. Specifically, this data includes the optional
1520 data written by the writeObject method and all data (including
1521 base classes) written by the Externalizable.writeExternal method.
1522 The @serialData tag can be used in the doc comment for the writeOb‐
1524 ject, readObject, writeExternal, readExternal, writeReplace, and
1525 readResolve methods.
1526 @since since-text
1528 Adds a "Since" heading with the specified since-text to the gen‐
1529 erated documentation. The text has no special internal structure.
1530 This tag is valid in any doc comment: overview, package, class,
1531 interface, constructor, method or field. This tag means that this
1532 change or feature has existed since the software release speci‐
1533 fied by the since-text. For example:
1534 @since 1.5
1535 For source code in the Java platform, this tag indicates the version
1538 of the Java platform API specification (not necessarily when it was
1539 added to the reference implementation). Multiple @since tags are
1540 allowed and are treated like multiple @author tags. You could use
1541 multiple tags if the prgram element is used by more than one API.
1542 @throws class-name description
1544 The @throws and @exception tags are synonyms. Adds a "Throws"
1545 subheading to the generated documentation, with the class-name
1546 and description text. The class-name is the name of the exception
1547 that may be thrown by the method. This tag is valid only in the
1548 doc comment for a method or constructor. If this class is not
1549 fully-specified, the Javadoc tool uses the search order to look
1550 up this class. Multiple @throws tags can be used in a given doc
1551 comment for the same or different exceptions.
1552 To ensure that all checked exceptions are documented, if a @throws
1554 tag does not exist for an exception in the throws clause, the
1555 Javadoc tool automatically adds that exception to the HTML output
1556 (with no description) as if it were documented with @throws tag.
1557 The @throws documentation is copied from an overridden method to a
1559 subclass only when the exception is explicitly declared in the over‐
1560 ridden method. The same is true for copying from an interface method
1561 to an implementing method. You can use {@inheritDoc} to force
1562 @throws to inherit documentation.
1563 For more details, see writing @throws tags @
1565 http://www.oracle.com/technetwork/java/javase/documenta‐
1566 tion/index-137868.html#@exception.
1567 {@value package.class#field}
1569 When {@value} is used (without any argument) in the doc comment
1570 of a static field, it displays the value of that constant:
1571 /**
1572 * The value of this constant is {@value}.
1573 */
1574 public static final String SCRIPT_START = "<script>"
1575 When used with argument package.class#field in any doc comment, it
1578 displays the value of the specified constant:
1579 /**
1580 * Evaluates the script starting with {@value #SCRIPT_START}.
1581 */
1582 public String evalScript(String script) {
1583 }
1584 The argument package.class#field takes a form identical to that of
1587 the @see argument, except that the member must be a static field.
1588 These values of these constants are also displayed on the Constant
1590 Field Values @
1591 http://docs.oracle.com/javase/7/docs/api/constant-values.html page.
1592 @version version-text
1594 Adds a "Version" subheading with the specified version-text to
1595 the generated docs when the -version option is used. This tag is
1596 intended to hold the current version number of the software that
1597 this code is part of (as opposed to @since, which holds the ver‐
1598 sion number where this code was introduced). The version-text has
1599 no special internal structure. To see where the version tag can
1600 be used, see Where Tags Can Be Used.
1601 A doc comment may contain multiple @version tags. If it makes sense,
1603 you can specify one version number per @version tag or multiple ver‐
1604 sion numbers per tag. In the former case, the Javadoc tool inserts a
1605 comma (,) and space between names. In the latter case, the entire
1606 text is simply copied to the generated document without being
1607 parsed. Therefore, you can use multiple names per line if you want a
1608 localized name separator other than comma.
1609 For more details, see writing @version tags @
1611 http://www.oracle.com/technetwork/java/javase/documenta‐
1612 tion/index-137868.html#@version.
1613 Where Tags Can Be Used
1615 The following sections describe where the tags can be used. Note that
1616 these tags can be used in all doc comments: @see, @since, @deprecated,
1617 {@link}, {@linkplain}, and {@docroot}.
1618 Overview Documentation Tags
1620 Overview tags are tags that can appear in the documentation comment for
1621 the overview page (which resides in the source file typically named
1622 overview.html). Like in any other documentation comments, these tags
1623 must appear after the main description.
1624 NOTE - The {@link} tag has a bug in overview documents in version 1.2
1626 -- the text appears properly but has no link. The {@docRoot} tag does
1627 not currently work in overview documents.
1628 Overview Tags
1630 o @see
1632 o @since
1634 o @author
1636 o @version
1638 o {@link}
1640 o {@linkplain}
1642 o {@docRoot}
1644 Package Documentation Tags
1646 Package tags are tags that can appear in the documentation comment for
1647 a package (which resides in the source file named package.html or pack‐
1648 age-info.java). The @serial tag can only be used here with the include
1649 or exclude argument.
1650 Package Tags
1652 o @see
1654 o @since
1656 o @serial
1658 o @author
1660 o @version
1662 o {@link}
1664 o {@linkplain}
1666 o {@docRoot}
1668 Class and Interface Documentation Tags
1670 The following are tags that can appear in the documentation comment for
1671 a class or interface. The @serial tag can only be used here with the
1672 include or exclude argument.
1673 Class/Interface Tags
1675 o @see
1677 o @since
1679 o @deprecated
1681 o @serial
1683 o @author
1685 o @version
1687 o {@link}
1689 o {@linkplain}
1691 o {@docRoot}
1693 An example of a class comment:
1694 /**
1695 * A class representing a window on the screen.
1696 * For example:
1697 * <pre>
1698 * Window win = new Window(parent);
1699 * win.show();
1700 * </pre>
1701 *
1702 * @author Sami Shaio
1703 * @version 1.13, 06/08/06
1704 * @see java.awt.BaseWindow
1705 * @see java.awt.Button
1706 */
1707 class Window extends BaseWindow {
1708 ...
1709 }
1710 Field Documentation Tags
1712 The following are the tags that can appear in
1713 Field Tags
1715 o @see
1717 o @since
1719 o @deprecated
1721 o @serial
1723 o @serialField
1725 o {@link}
1727 o {@linkplain}
1729 o {@docRoot}
1731 o {@value}
1733 An example of a field comment:
1734 /**
1735 * The X-coordinate of the component.
1736 *
1737 * @see #getLocation()
1738 */
1739 int x = 1263732;
1740 Constructor and Method Documentation Tags
1742 The following are the tags that can appear in the documentation comment
1743 for a constructor or method, except for @return, which cannot appear in
1744 a constructor, and {@inheritDoc}, which has certain restrictions. The
1745 @serialData tag can only be used in the doc comment for certain serial‐
1746 ization methods.
1747 Method/Constructor Tags
1749 o @see
1751 o @since
1753 o @deprecated
1755 o @param
1757 o @return
1759 o @throws and @exception
1761 o @serialData
1763 o {@link}
1765 o {@linkplain}
1767 o {@inheritDoc}
1769 o {@docRoot}
1771 An example of a method doc comment:
1772 /**
1773 * Returns the character at the specified index. An index
1774 * ranges from <code>0</code> to <code>length() - 1</code>.
1775 *
1776 * @param index the index of the desired character.
1777 * @return the desired character.
1778 * @exception StringIndexOutOfRangeException
1779 * if the index is not in the range <code>0</code>
1780 * to <code>length()-1</code>.
1781 * @see java.lang.Character#charValue()
1782 */
1783 public char charAt(int index) {
1784 ...
1785 }
1786
1788 The javadoc tool uses doclets to determine its output. The Javadoc tool
1789 uses the default standard doclet unless a custom doclet is specified
1790 with the -doclet option. The Javadoc tool provides a set of com‐
1791 mand-line options that can be used with any doclet -- these options are
1792 described below under the sub-heading Javadoc Options. The standard
1793 doclet provides an additional set of command-line options that are
1794 described below under the sub-heading Options Provided by the Standard
1795 Doclet. All option names are case-insensitive, though their arguments
1796 can be case-sensitive.
1797 The options are:
1799 Options shown in italic are the Javadoc core options, which are pro‐
1801 vided by the front end of the Javadoc tool and are available to all
1802 doclets. The standard doclet itself provides the non-italic options.
1803 Javadoc Options
1805 -overview path/filename
1806 Specifies that javadoc should retrieve the text for the overview
1807 documentation from the "source" file specified by path/filename
1808 and place it on the Overview page (overview-summary.html). The
1809 path/filename is relative to the current directory.
1810 While you can use any name you want for filename and place it
1811 anywhere you want for path, a typical thing to do is to name it
1812 overview.html and place it in the source tree at the directory
1813 that contains the topmost package directories. In this location,
1814 no path is needed when documenting packages, since -sourcepath
1815 will point to this file. For example, if the source tree for the
1816 java.lang package is /src/classes/java/lang/, then you could
1817 place the overview file at /src/classes/overview.html. See Real
1818 World Example.
1819 For information about the file specified by path/filename, see
1820 overview comment file.
1821 Note that the overview page is created only if you pass into
1822 javadoc two or more package names. For further explanation, see
1823 HTML Frames.)
1824 The title on the overview page is set by -doctitle.
1825 -public
1827 Shows only public classes and members.
1828 -protected
1830 Shows only protected and public classes and members. This is the
1831 default.
1832 -package
1834 Shows only package, protected, and public classes and members.
1835 -private
1837 Shows all classes and members.
1838 -help
1840 Displays the online help, which lists these javadoc and doclet
1841 command line options.
1842 -doclet class
1844 Specifies the class file that starts the doclet used in generat‐
1845 ing the documentation. Use the fully-qualified name. This doclet
1846 defines the content and formats the output. If the -doclet option
1847 is not used, javadoc uses the standard doclet for generating the
1848 default HTML format. This class must contain the start(Root)
1849 method. The path to this starting class is defined by the
1850 -docletpath option.
1851 For example, to call the MIF doclet, use:
1852 -doclet com.sun.tools.doclets.mif.MIFDoclet
1853 For full, working examples of running a particular doclet, see
1854 the MIF Doclet documentation @
1855 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
1856 -docletpath classpathlist
1858 Specifies the path to the doclet starting class file (specified
1859 with the -doclet option) and any jar files it depends on. If the
1860 starting class file is in a jar file, then this specifies the
1861 path to that jar file, as shown in the example below. You can
1862 specify an absolute path or a path relative to the current direc‐
1863 tory. If classpathlist contains multiple paths or jar files, they
1864 should be separated with a colon (:) on Solaris and a semi-colon
1865 (;) on Windows. This option is not necessary if the doclet start‐
1866 ing class is already in the search path.
1867 Example of path to jar file that contains the starting doclet
1868 class file. Notice the jar filename is included.
1869 -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
1870 Example of path to starting doclet class file. Notice the class
1871 filename is omitted.
1872 -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
1873 For full, working examples of running a particular doclet, see
1874 the MIF Doclet documentation @
1875 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
1876 -1.1
1878 This feature has been removed from Javadoc 1.4. There is no
1879 replacement for it. This option created documentation with the
1880 appearance and functionality of documentation generated by
1881 Javadoc 1.1 (it never supported nested classes). If you need this
1882 option, use Javadoc 1.2 or 1.3 instead.
1883 -source release
1885 Specifies the version of source code accepted. The following val‐
1886 ues for release are allowed:
1887 o 1.5 - javadoc accepts code containing generics and other lan‐
1889 guage features introduced in JDK 1.5. The compiler defaults to
1890 the 1.5 behavior if the -source flag is not used.
1891 o 1.4 - javadoc accepts code containing assertions, which were
1893 introduced in JDK 1.4.
1894 o 1.3 - javadoc does not support assertions, generics, or other
1896 language features introduced after JDK 1.3.
1897 Use the value of release corresponding to that used when compiling
1898 the code with javac.
1899 -sourcepath sourcepathlist
1901 Specifies the search paths for finding source files (.java) when
1902 passing package names or -subpackages into the javadoc command.
1903 The sourcepathlist can contain multiple paths by separating them
1904 with a colon (:). The Javadoc tool will search in all subdirecto‐
1905 ries of the specified paths. Note that this option is not only
1906 used to locate the source files being documented, but also to
1907 find source files that are not being documented but whose com‐
1908 ments are inherited by the source files being documented.
1909 Note that you can use the -sourcepath option only when passing
1910 package names into the javadoc command -- it will not locate
1911 .java files passed into the javadoc command. (To locate .java
1912 files, cd to that directory or include the path ahead of each
1913 file, as shown at Documenting One or More Classes.) If -sour‐
1914 cepath is omitted, javadoc uses the class path to find the source
1915 files (see -classpath). Therefore, the default -sourcepath is the
1916 value of class path. If -classpath is omitted and you are passing
1917 package names into javadoc, it looks in the current directory
1918 (and subdirectories) for the source files.
1919 Set sourcepathlist to the root directory of the source tree for
1920 the package you are documenting. For example, suppose you want to
1921 document a package called com.mypackage whose source files are
1922 located at:
1923 /home/user/src/com/mypackage/*.java
1924 In this case you would specify the sourcepath to /home/user/src,
1925 the directory that contains com/mypackage, and then supply the
1926 package name com.mypackage:
1927 % javadoc -sourcepath /home/user/src/ com.mypackage
1928 This is easy to remember by noticing that if you concatenate the
1929 value of sourcepath and the package name together and change the
1930 dot to a slash "/", you end up with the full path to the package:
1931 /home/user/src/com/mypackage.
1932 To point to two source paths:
1933 % javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage
1934 -classpath classpathlist
1936 Specifies the paths where javadoc will look for referenced
1937 classes (.class files) -- these are the documented classes plus
1938 any classes referenced by those classes. The classpathlist can
1939 contain multiple paths by separating them with a colon (:). The
1940 Javadoc tool will search in all subdirectories of the specified
1941 paths. Follow the instructions in class path @
1942 http://docs.oracle.com/javase/7/docs/tech‐
1943 notes/tools/index.html#general documentation for specifying
1944 classpathlist.
1945 If -sourcepath is omitted, the Javadoc tool uses -classpath to
1946 find the source files as well as class files (for backward com‐
1947 patibility). Therefore, if you want to search for source and
1948 class files in separate paths, use both -sourcepath and -class‐
1949 path.
1950 For example, if you want to document com.mypackage, whose source
1951 files reside in the directory /home/user/src/com/mypackage, and
1952 if this package relies on a library in /home/user/lib, you would
1953 specify:
1954 % javadoc -classpath /home/user/lib -sourcepath /home/user/src com.mypackage
1955 As with other tools, if you do not specify -classpath, the
1956 Javadoc tool uses the CLASSPATH environment variable, if it is
1957 set. If both are not set, the Javadoc tool searches for classes
1958 from the current directory.
1959 For an in-depth description of how the Javadoc tool uses -class‐
1960 path to find user classes as it relates to extension classes and
1961 bootstrap classes, see How Classes Are Found @
1962 http://docs.oracle.com/javase/7/docs/technotes/tools/finding‐
1963 classes.html.
1964 As a special convenience, a class path element containing a base‐
1965 name of * is considered equivalent to specifying a list of all
1966 the files in the directory with the extension .jar or .JAR (a
1967 Java program cannot tell the difference between the two invoca‐
1968 tions).
1969 For example, if directory foo contains a.jar and b.JAR, then the
1970 class path element foo/* is expanded to a A.jar:b.JAR, except
1971 that the order of jar files is unspecified. All jar files in the
1972 specified directory, even hidden ones, are included in the list.
1973 A classpath entry consisting simply of * expands to a list of all
1974 the jar files in the current directory. The CLASSPATH environment
1975 variable, where defined, will be similarly expanded. Any class‐
1976 path wildcard expansion occurs before the Java virtual machine is
1977 started -- no Java program will ever see unexpanded wildcards
1978 except by querying the environment. For example; by invoking Sys‐
1979 tem.getenv("CLASSPATH").
1980 -subpackages package1:package2:...
1982 Generates documentation from source files in the specified pack‐
1983 ages and recursively in their subpackages. This option is useful
1984 when adding new subpackages to the source code, as they are auto‐
1985 matically included. Each package argument is any top-level sub‐
1986 package (such as java) or fully qualified package (such as
1987 javax.swing) that does not need to contain source files. Argu‐
1988 ments are separated by colons (on all operating systmes). Wild‐
1989 cards are not needed or allowed. Use -sourcepath to specify where
1990 to find the packages. This option is smart about not processing
1991 source files that are in the source tree but do not belong to the
1992 packages, as described at processing of source files.
1993 For example:
1994 % javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
1995 This command generates documentation for packages named "java"
1996 and "javax.swing" and all their subpackages.
1997 You can use -subpackages in conjunction with -exclude to exclude
1998 specific packages.
1999 -exclude packagename1:packagename2:...
2001 Unconditionally excludes the specified packages and their sub‐
2002 packages from the list formed by -subpackages. It excludes those
2003 packages even if they would otherwise be included by some previ‐
2004 ous or later -subpackages option. For example:
2005 % javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
2006 would include java.io, java.util, and java.math (among others),
2007 but would exclude packages rooted at java.net and java.lang.
2008 Notice this excludes java.lang.ref, a subpackage of java.lang).
2009 -bootclasspath classpathlist
2011 Specifies the paths where the boot classes reside. These are nom‐
2012 inally the Java platform classes. The bootclasspath is part of
2013 the search path the Javadoc tool will use to look up source and
2014 class files. See How Classes Are Found @
2015 http://docs.oracle.com/javase/7/docs/technotes/tools/finding‐
2016 classes.html#srcfiles. for more details. Separate directories in
2017 classpathlist with colons (:).
2018 -extdirs dirlist
2020 Specifies the directories where extension classes reside. These
2021 are any classes that use the Java Extension mechanism. The
2022 extdirs is part of the search path the Javadoc tool will use to
2023 look up source and class files. See -classpath (above) for more
2024 details. Separate directories in dirlist with colons (:).
2025 -verbose
2027 Provides more detailed messages while javadoc is running. Without
2028 the verbose option, messages appear for loading the source files,
2029 generating the documentation (one message per source file), and
2030 sorting. The verbose option causes the printing of additional
2031 messages specifying the number of milliseconds to parse each java
2032 source file.
2033 -quiet
2035 Shuts off non-error and non-warning messages, leaving only the
2036 warnings and errors appear, making them easier to view. Also sup‐
2037 presses the version string.
2038 -breakiterator
2040 Uses the internationalized sentence boundary of
2041 java.text.BreakIterator @
2042 http://docs.oracle.com/javase/7/docs/api/java/text/BreakItera‐
2043 tor.html to determine the end of the first sentence for English
2044 (all other locales already use BreakIterator), rather than an
2045 English language, locale-specific algorithm. By first sentence,
2046 we mean the first sentence in the main description of a package,
2047 class or member. This sentence is copied to the package, class or
2048 member summary, and to the alphabetic index.
2049 From JDK 1.2 forward, the BreakIterator class is already used to
2050 determine the end of sentence for all languages but English.
2051 Therefore, the -breakiterator option has no effect except for
2052 English from 1.2 forward. English has its own default algorithm:
2053 o English default sentence-break algorithm - Stops at a period
2055 followed by a space or a HTML block tag, such as <P>.
2056 o Breakiterator sentence-break algorithm - In general, stops at a
2058 period, question mark or exclamation mark followed by a space
2059 if the next word starts with a capital letter. This is meant to
2060 handle most abbreviations (such as "The serial no. is valid",
2061 but won't handle "Mr. Smith"). Doesn't stop at HTML tags or
2062 sentences that begin with numbers or symbols. Stops at the last
2063 period in "../filename", even if embedded in an HTML tag.
2064 NOTE: We have removed from 1.5.0 the breakiterator warning messages
2065 that were in 1.4.x and have left the default sentence-break algo‐
2066 rithm unchanged. That is, the -breakiterator option is not the
2067 default in 1.5.0, nor do we expect it to become the default. This is
2068 a reversal from our former intention that the default would change
2069 in the "next major release" (1.5.0). This means if you have not mod‐
2070 ified your source code to eliminate the breakiterator warnings in
2071 1.4.x, then you don't have to do anything, and the warnings go away
2072 starting with 1.5.0. The reason for this reversal is because any
2073 benefit to having breakiterator become the default would be out‐
2074 weighed by the incompatible source change it would require. We
2075 regret any extra work and confusion this has caused.
2076 -locale language_country_variant
2078 Important - The -locale option must be placed ahead (to the left)
2079 of any options provided by the standard doclet or any other
2080 doclet. Otherwise, the navigation bars will appear in English.
2081 This is the only command-line option that is order-dependent.
2082 Specifies the locale that javadoc uses when generating documenta‐
2083 tion. The argument is the name of the locale, as described in
2084 java.util.Locale documentation, such as en_US (English, United
2085 States) or en_US_WIN (Windows variant).
2086 Specifying a locale causes javadoc to choose the resource files
2087 of that locale for messages (strings in the navigation bar, head‐
2088 ings for lists and tables, help file contents, comments in
2089 stylesheet.css, and so forth). It also specifies the sorting
2090 order for lists sorted alphabetically, and the sentence separator
2091 to determine the end of the first sentence. It does not determine
2092 the locale of the doc comment text specified in the source files
2093 of the documented classes.
2094 -encoding name
2096 Specifies the encoding name of the source files, such as
2097 EUCJIS/SJIS. If this option is not specified, the platform
2098 default converter is used.
2099 Also see -docencoding and -charset.
2100 -Jflag
2102 Passes flag directly to the runtime system java that runs
2103 javadoc. Notice there must be no space between the J and the
2104 flag. For example, if you need to ensure that the system sets
2105 aside 32 megabytes of memory in which to process the generated
2106 documentation, then you would call the -Xmx option of java as
2107 follows (-Xms is optional, as it only sets the size of initial
2108 memory, which is useful if you know the minimum amount of memory
2109 required):
2110 % javadoc -J-Xmx32m -J-Xms32m com.mypackage
2111 To tell what version of javadoc you are using, call the "-ver‐
2112 sion" option of java:
2113 % javadoc -J-version
2114 java version "1.2"
2115 Classic VM (build JDK-1.2-V, green threads, sunwjit)
2116 (The version number of the standard doclet appears in its output
2117 stream.)
2118 Options Provided by the Standard Doclet
2120 -d directory
2121 Specifies the destination directory where javadoc saves the gen‐
2122 erated HTML files. (The "d" means "destination.") Omitting this
2123 option causes the files to be saved to the current directory. The
2124 value directory can be absolute, or relative to the current work‐
2125 ing directory. As of 1.4, the destination directory is automati‐
2126 cally created when javadoc is run.
2127 For example, the following generates the documentation for the
2128 package com.mypackage and saves the results in the
2129 /home/user/doc/ directory:
2130 % javadoc -d /home/user/doc com.mypackage
2131 -use
2133 Includes one "Use" page for each documented class and package.
2134 The page describes what packages, classes, methods, constructors
2135 and fields use any API of the given class or package. Given class
2136 C, things that use class C would include subclasses of C, fields
2137 declared as C, methods that return C, and methods and construc‐
2138 tors with parameters of type C.
2139 For example, let us look at what might appear on the "Use" page
2140 for String. The getName() method in the java.awt.Font class
2141 returns type String. Therefore, getName() uses String, and you
2142 will find that method on the "Use" page for String.
2143 Note that this documents only uses of the API, not the implemen‐
2144 tation. If a method uses String in its implementation but does
2145 not take a string as an argument or return a string, that is not
2146 considered a "use" of String.
2147 You can access the generated "Use" page by first going to the
2148 class or package, then clicking on the "Use" link in the naviga‐
2149 tion bar.
2150 -version
2152 Includes the @version text in the generated docs. This text is
2153 omitted by default. To tell what version of the Javadoc tool you
2154 are using, use the -J-version option.
2155 -author
2157 Includes the @author text in the generated docs.
2158 -splitindex
2160 Splits the index file into multiple files, alphabetically, one
2161 file per letter, plus a file for any index entries that start
2162 with non-alphabetical characters.
2163 -windowtitle title
2165 Specifies the title to be placed in the HTML <title> tag. This
2166 appears in the window title and in any browser bookmarks
2167 (favorite places) that someone creates for this page. This title
2168 should not contain any HTML tags, as the browser will not prop‐
2169 erly interpret them. Any internal quotation marks within title
2170 may have to be escaped. If -windowtitle is omitted, the Javadoc
2171 tool uses the value of -doctitle for this option.
2172 % javadoc -windowtitle "Java SE Platform" com.mypackage
2173 -doctitle title
2175 Specifies the title to be placed near the top of the overview
2176 summary file. The title will be placed as a centered, level-one
2177 heading directly beneath the upper navigation bar. The title may
2178 contain html tags and white space, though if it does, it must be
2179 enclosed in quotes. Any internal quotation marks within title may
2180 have to be escaped.
2181 % javadoc -doctitle "Java(TM)" com.mypackage
2182 -title title
2184 This option no longer exists. It existed only in Beta versions of
2185 Javadoc 1.2. It has been renamed to -doctitle. This option is
2186 being renamed to make it clear that it defines the document title
2187 rather than the window title.
2188 -header header
2190 Specifies the header text to be placed at the top of each output
2191 file. The header will be placed to the right of the upper naviga‐
2192 tion bar. header may contain HTML tags and white space, though if
2193 it does, it must be enclosed in quotes. Any internal quotation
2194 marks within header may have to be escaped.
2195 % javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage
2196 -footer footer
2198 Specifies the footer text to be placed at the bottom of each out‐
2199 put file. The footer will be placed to the right of the lower
2200 navigation bar. footer may contain html tags and white space,
2201 though if it does, it must be enclosed in quotes. Any internal
2202 quotation marks within footer may have to be escaped.
2203 -top
2205 Specifies the text to be placed at the top of each output file.
2206 -bottom text
2208 Specifies the text to be placed at the bottom of each output
2209 file. The text will be placed at the bottom of the page, below
2210 the lower navigation bar. The text may contain HTML tags and
2211 white space, though if it does, it must be enclosed in quotes.
2212 Any internal quotation marks within text may have to be escaped.
2213 -link extdocURL
2215 Creates links to existing javadoc-generated documentation of
2216 external referenced classes. It takes one argument:
2217 o extdocURL is the absolute or relative URL of the directory con‐
2219 taining the external javadoc-generated documentation you want
2220 to link to. Examples are shown below. The package-list file
2221 must be found in this directory (otherwise, use -linkoffline).
2222 The Javadoc tool reads the package names from the package-list
2223 file and then links to those packages at that URL. When the
2224 Javadoc tool is run, the extdocURL value is copied literally
2225 into the <A HREF> links that are created. Therefore, extdocURL
2226 must be the URL to the directory, not to a file.
2227 You can use an absolute link for extdocURL to enable your docs
2228 to link to a document on any website, or can use a relative
2229 link to link only to a relative location. If relative, the
2230 value you pass in should be the relative path from the destina‐
2231 tion directory (specified with -d) to the directory containing
2232 the packages being linked to.
2233 When specifying an absolute link you normally use an http:
2234 link. However, if you want to link to a file system that has no
2235 web server, you can use a file: link -- however, do this only
2236 if everyone wanting to access the generated documentation
2237 shares the same file system.
2238 In all cases, and on all operating systems, you should use a
2239 forward slash as the separator, whether the URL is absolute or
2240 relative, and "http:" or "file:" based (as specified in the URL
2241 Memo @
2242 http://www.ietf.org/rfc/rfc1738.txt).
2243 Absolute http: based link:
2245 -link http://<host>/<directory>/<directory>/.../<name>
2246 Absolute file: based link:
2248 -link file://<host>/<directory>/<directory>/.../<name>
2249 Relative link:
2251 -link <directory>/<directory>/.../<name>
2252 You can specify multiple -link options in a given javadoc run to
2253 link to multiple documents.
2254 Choosing between -linkoffline and -link:
2255 Use -link:
2256 o when using a relative path to the external API document, or
2258 o when using an absolute URL to the external API document, if
2260 your shell allows a program to open a connection to that URL
2261 for reading.
2262 Use -linkoffline:
2263 o when using an absolute URL to the external API document, if
2265 your shell does not allow a program to open a connection to
2266 that URL for reading. This can occur if you are behind a fire‐
2267 wall and the document you want to link to is on the other side.
2268 Example using absolute links to the external docs - Let us say you
2269 want to link to the java.lang, java.io and other Java Platform pack‐
2270 ages at http://docs.oracle.com/javase/7/docs/api/ @
2271 http://docs.oracle.com/javase/7/docs/api/. The following command
2272 generates documentation for the package com.mypackage with links to
2273 the Java SE Platform packages. The generated documentation will con‐
2274 tain links to the Object class, for example, in the class trees.
2275 (Other options, such as -sourcepath and -d, are not shown.)
2276 % javadoc -link http://docs.oracle.com/javase/7/docs/api/ com.mypackage
2277 Example using relative links to the external docs - Let us say you
2278 have two packages whose docs are generated in different runs of the
2279 Javadoc tool, and those docs are separated by a relative path. In
2280 this example, the packages are com.apipackage, an API, and com.spi‐
2281 package, an SPI (Service Provide Interface). You want the documenta‐
2282 tion to reside in docs/api/com/apipackage and docs/spi/com/spipack‐
2283 age. Assuming the API package documentation is already generated,
2284 and that docs is the current directory, you would document the SPI
2285 package with links to the API documentation by running:
2286 % javadoc -d ./spi -link ../api com.spipackage
2287 Notice the -link argument is relative to the destination directory
2288 (docs/spi).
2289 Details - The -link option enables you to link to classes referenced
2290 to by your code but not documented in the current javadoc run. For
2291 these links to go to valid pages, you must know where those HTML
2292 pages are located, and specify that location with extdocURL. This
2293 allows, for instance, third party documentation to link to java.*
2294 documentation on http://java.sun.com.
2295 Omit the -link option for javadoc to create links only to API within
2296 the documentation it is generating in the current run. (Without the
2297 -link option, the Javadoc tool does not create links to documenta‐
2298 tion for external references, because it does not know if or where
2299 that documentation exists.)
2300 This option can create links in several places in the generated doc‐
2301 umentation.
2302 Another use is for cross-links between sets of packages: Execute
2303 javadoc on one set of packages, then run javadoc again on another
2304 set of packages, creating links both ways between both sets.
2305 How a Class Must be Referenced - For a link to an external refer‐
2306 enced class to actually appear (and not just its text label), the
2307 class must be referenced in the following way. It is not sufficient
2308 for it to be referenced in the body of a method. It must be refer‐
2309 enced in either an import statement or in a declaration. Here are
2310 examples of how the class java.io.File can be referenced:
2311 o In any kind of import statement: by wildcard import, import
2313 explicitly by name, or automatically import for java.lang.*.
2314 For example, this would suffice:
2315 import java.io.*;
2316 In 1.3.x and 1.2.x, only an explicit import by name works -- a
2317 wildcard import statement does not work, nor does the automatic
2318 import java.lang.*.
2319 o In a declaration:
2321 void foo(File f) {}
2322 The reference and be in the return type or parameter type of a
2323 method, constructor, field, class or interface, or in an imple‐
2324 ments, extends or throws statement.
2325 An important corollary is that when you use the -link option, there
2326 may be many links that unintentionally do not appear due to this
2327 constraint. (The text would appear without a hypertext link.) You
2328 can detect these by the warnings they emit. The most innocuous way
2329 to properly reference a class and thereby add the link would be to
2330 import that class, as shown above.
2331 Package List - The -link option requires that a file named pack‐
2332 age-list, which is generated by the Javadoc tool, exist at the URL
2333 you specify with -link. The package-list file is a simple text file
2334 that lists the names of packages documented at that location. In the
2335 earlier example, the Javadoc tool looks for a file named pack‐
2336 age-list at the given URL, reads in the package names and then links
2337 to those packages at that URL.
2338 For example, the package list for the Java SE 6 API is located at
2339 http://docs.oracle.com/javase/7/docs/api/package-list @
2340 http://docs.oracle.com/javase/7/docs/api/package-list. and starts as
2341 follows:
2342 java.applet
2343 java.awt
2344 java.awt.color
2345 java.awt.datatransfer
2346 java.awt.dnd
2347 java.awt.event
2348 java.awt.font
2349 etc.
2350 When javadoc is run without the -link option, when it encounters a
2351 name that belongs to an external referenced class, it prints the
2352 name with no link. However, when the -link option is used, the
2353 Javadoc tool searches the package-list file at the specified
2354 extdocURL location for that package name. If it finds the package
2355 name, it prefixes the name with extdocURL.
2356 In order for there to be no broken links, all of the documentation
2357 for the external references must exist at the specified URLs. The
2358 Javadoc tool will not check that these pages exist -- only that the
2359 package-list exists.
2360 Multiple Links - You can supply multiple -link options to link to
2361 any number of external generated documents. Javadoc 1.2 has a
2362 known bug which prevents you from supplying more than one -link com‐
2363 mand. This was fixed in 1.2.2.
2364 Specify a different link option for each external document to link
2365 to:
2366 % javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn
2367 com.mypackage
2368 where extdocURL1, extdocURL2, ... extdocURLn point respectively to
2369 the roots of external documents, each of which contains a file named
2370 package-list.
2371 Cross-links - Note that "bootstrapping" may be required when
2372 cross-linking two or more documents that have not previously been
2373 generated. In other words, if package-list does not exist for either
2374 document, when you run the Javadoc tool on the first document, the
2375 package-list will not yet exist for the second document. Therefore,
2376 to create the external links, you must re-generate the first docu‐
2377 ment after generating the second document.
2378 In this case, the purpose of first generating a document is to cre‐
2379 ate its package-list (or you can create it by hand it if you're cer‐
2380 tain of the package names). Then generate the second document with
2381 its external links. The Javadoc tool prints a warning if a needed
2382 external package-list file does not exist.
2383 -linkoffline extdocURL packagelistLoc
2385 This option is a variation of -link; they both create links to
2386 javadoc-generated documentation for external referenced classes.
2387 Use the -linkoffline option when linking to a document on the web
2388 when the Javadoc tool itself is "offline" -- that is, it cannot
2389 access the document through a web connection.
2390 More specifically, use -linkoffline if the external document's
2391 package-list file is not accessible or does not exist at the
2392 extdocURL location but does exist at a different location, which
2393 can be specified by packageListLoc (typically local). Thus, if
2394 extdocURL is accessible only on the World Wide Web, -linkoffline
2395 removes the constraint that the Javadoc tool have a web connec‐
2396 tion when generating the documentation.
2397 Another use is as a "hack" to update docs: After you have run
2398 javadoc on a full set of packages, then you can run javadoc again
2399 on onlya smaller set of changed packages, so that the updated
2400 files can be inserted back into the original set. Examples are
2401 given below.
2402 The -linkoffline option takes two arguments -- the first for the
2403 string to be embedded in the <a href> links, the second telling
2404 it where to find package-list:
2405 o extdocURL is the absolute or relative URL of the directory con‐
2407 taining the external javadoc-generated documentation you want
2408 to link to. If relative, the value should be the relative path
2409 from the destination directory (specified with -d) to the root
2410 of the packages being linked to. For more details, see
2411 extdocURL in the -link option.
2412 o packagelistLoc is the path or URL to the directory containing
2414 the package-list file for the external documentation. This can
2415 be a URL (http: or file:) or file path, and can be absolute or
2416 relative. If relative, make it relative to the current direc‐
2417 tory from where javadoc was run. Do not include the pack‐
2418 age-list filename.
2419 You can specify multiple -linkoffline options in a given javadoc
2420 run. (Prior to 1.2.2, it could be specified only once.)
2421 Example using absolute links to the external docs - Let us say you
2422 want to link to the java.lang, java.io and other Java SE Platform
2423 packages at http://docs.oracle.com/javase/7/docs/api/, but your
2424 shell does not have web access. You could open the package-list file
2425 in a browser at http://docs.oracle.com/javase/7/docs/api/pack‐
2426 age-list @
2427 http://docs.oracle.com/javase/7/docs/api/package-list, save it to a
2428 local directory, and point to this local copy with the second argu‐
2429 ment, packagelistLoc. In this example, the package list file has
2430 been saved to the current directory "." . The following command gen‐
2431 erates documentation for the package com.mypackage with links to the
2432 Java SE Platform packages. The generated documentation will contain
2433 links to the Object class, for example, in the class trees. (Other
2434 necessary options, such as -sourcepath, are not shown.)
2435 % javadoc -linkoffline http://docs.oracle.com/javase/7/docs/api/ . com.mypackage
2436 Example using relative links to the external docs - It's not very
2437 common to use -linkoffline with relative paths, for the simple rea‐
2438 son that -link usually suffices. When using -linkoffline, the pack‐
2439 age-list file is generally local, and when using relative links, the
2440 file you are linking to is also generally local. So it is usually
2441 unnecessary to give a different path for the two arguments to
2442 -linkoffline. When the two arguments are identical, you can use
2443 -link. See the -link relative example.
2444 Manually Creating a package-list File - If a package-list file does
2445 not yet exist, but you know what package names your document will
2446 link to, you can create your own copy of this file by hand and spec‐
2447 ify its path with packagelistLoc. An example would be the previous
2448 case where the package list for com.spipackage did not exist when
2449 com.apipackage was first generated. This technique is useful when
2450 you need to generate documentation that links to new external docu‐
2451 mentation whose package names you know, but which is not yet pub‐
2452 lished. This is also a way of creating package-list files for pack‐
2453 ages generated with Javadoc 1.0 or 1.1, where package-list files
2454 were not generated. Likewise, two companies can share their unpub‐
2455 lished package-list files, enabling them to release their
2456 cross-linked documentation simultaneously.
2457 Linking to Multiple Documents - You can include -linkoffline once
2458 for each generated document you want to refer to (each option is
2459 shown on a separate line for clarity):
2460 % javadoc -linkoffline extdocURL1 packagelistLoc1 \
2461 -linkoffline extdocURL2 packagelistLoc2 \
2462 ...
2463 Updating docs - Another use for -linkoffline option is useful if
2464 your project has dozens or hundreds of packages, if you have already
2465 run javadoc on the entire tree, and now, in a separate run, you want
2466 to quickly make some small changes and re-run javadoc on just a
2467 small portion of the source tree. This is somewhat of a hack in that
2468 it works properly only if your changes are only to doc comments and
2469 not to declarations. If you were to add, remove or change any decla‐
2470 rations from the source code, then broken links could show up in the
2471 index, package tree, inherited member lists, use page, and other
2472 places.
2473 First, you create a new destination directory (call it update) for
2474 this new small run. Let us say the original destination directory
2475 was named html. In the simplest example, cd to the parent of html.
2476 Set the first argument of -linkoffline to the current directory "."
2477 and set the second argument to the relative path to html, where it
2478 can find package-list, and pass in only the package names of the
2479 packages you want to update:
2480 % javadoc -d update -linkoffline . html com.mypackage
2481 When the Javadoc tool is done, copy these generated class pages in
2482 update/com/package (not the overview or index), over the original
2483 files in html/com/package.
2484 -linksource
2486 Creates an HTML version of each source file (with line numbers)
2487 and adds links to them from the standard HTML documentation.
2488 Links are created for classes, interfaces, constructors, methods
2489 and fields whose declarations are in a source file. Otherwise,
2490 links are not created, such as for default constructors and gen‐
2491 erated classes.
2492 This option exposes all private implementation details in the
2493 included source files, including private classes, private fields,
2494 and the bodies of private methods, regardless of the -public,
2495 -package, -protected and -private options. Unless you also use
2496 the -private option, not all private classes or interfaces will
2497 necessarily be accessible via links.
2498 Each link appears on the name of the identifier in its declara‐
2499 tion. For example, the link to the source code of the Button
2500 class would be on the word "Button":
2501 public class Button
2502 extends Component
2503 implements Accessible
2504 and the link to the source code of the getLabel() method in the
2505 Button class would be on the word "getLabel":
2506 public String getLabel()
2507 -group groupheading packagepattern:packagepattern:...
2509 Separates packages on the overview page into whatever groups you
2510 specify, one group per table. You specify each group with a dif‐
2511 ferent -group option. The groups appear on the page in the order
2512 specified on the command line; packages are alphabetized within a
2513 group. For a given -group option, the packages matching the list
2514 of packagepattern expressions appear in a table with the heading
2515 groupheading.
2516 o groupheading can be any text, and can include white space. This
2518 text is placed in the table heading for the group.
2519 o packagepattern can be any package name, or can be the start of
2521 any package name followed by an asterisk (*). The asterisk is a
2522 wildcard meaning "match any characters". This is the only wild‐
2523 card allowed. Multiple patterns can be included in a group by
2524 separating them with colons (:).
2525 NOTE: If using an asterisk in a pattern or pattern list, the pattern
2526 list must be inside quotes, such as "java.lang*:java.util"
2527 If you do not supply any -group option, all packages are placed in
2528 one group with the heading "Packages". If the all groups do not
2529 include all documented packages, any leftover packages appear in a
2530 separate group with the heading "Other Packages".
2531 For example, the following option separates the four documented
2532 packages into core, extension and other packages. Notice the trail‐
2533 ing "dot" does not appear in "java.lang*" -- including the dot, such
2534 as "java.lang.*" would omit the java.lang package.
2535 % javadoc -group "Core Packages" "java.lang*:java.util"
2536 -group "Extension Packages" "javax.*"
2537 java.lang java.lang.reflect java.util javax.servlet java.new
2538 This results in the groupings:
2539 Core Packages
2541 java.lang java.lang.reflect java.util
2542 Extension Packages
2544 javax.servlet
2545 Other Packages
2547 java.new
2548 -nodeprecated
2550 Prevents the generation of any deprecated API at all in the docu‐
2551 mentation. This does what -nodeprecatedlist does, plus it does
2552 not generate any deprecated API throughout the rest of the docu‐
2553 mentation. This is useful when writing code and you don't want to
2554 be distracted by the deprecated code.
2555 -nodeprecatedlist
2557 Prevents the generation of the file containing the list of depre‐
2558 cated APIs (deprecated-list.html) and the link in the navigation
2559 bar to that page. (However, javadoc continues to generate the
2560 deprecated API throughout the rest of the document.) This is use‐
2561 ful if your source code contains no deprecated API, and you want
2562 to make the navigation bar cleaner.
2563 -nosince
2565 Omits from the generated docs the "Since" sections associated
2566 with the @since tags.
2567 -notree
2569 Omits the class/interface hierarchy pages from the generated
2570 docs. These are the pages you reach using the "Tree" button in
2571 the navigation bar. The hierarchy is produced by default.
2572 -noindex
2574 Omits the index from the generated docs. The index is produced by
2575 default.
2576 -nohelp
2578 Omits the HELP link in the navigation bars at the top and bottom
2579 of each page of output.
2580 -nonavbar
2582 Prevents the generation of the navigation bar, header and footer,
2583 otherwise found at the top and bottom of the generated pages. Has
2584 no affect on the "bottom" option. The -nonavbar option is useful
2585 when you are interested only in the content and have no need for
2586 navigation, such as converting the files to PostScript or PDF for
2587 print only.
2588 -helpfile path/filename
2590 Specifies the path of an alternate help file path/filename that
2591 the HELP link in the top and bottom navigation bars link to.
2592 Without this option, the Javadoc tool automatically creates a
2593 help file help-doc.html that is hard-coded in the Javadoc tool.
2594 This option enables you to override this default. The filename
2595 can be any name and is not restricted to help-doc.html -- the
2596 Javadoc tool will adjust the links in the navigation bar accord‐
2597 ingly. For example:
2598 % javadoc -helpfile /home/user/myhelp.html java.awt
2599 -stylesheetfile path/filename
2601 Specifies the path of an alternate HTML stylesheet file. Without
2602 this option, the Javadoc tool automatically creates a stylesheet
2603 file stylesheet.css that is hard-coded in the Javadoc tool. This
2604 option enables you to override this default. The filename can be
2605 any name and is not restricted to stylesheet.css. For example:
2606 % javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage
2607 -serialwarn
2609 Generates compile-time warnings for missing @serial tags. By
2610 default, Javadoc 1.2.2 (and later versions) generates no serial
2611 warnings. (This is a reversal from earlier versions.) Use this
2612 option to display the serial warnings, which helps to properly
2613 document default serializable fields and writeExternal methods.
2614 -charset name
2616 Specifies the HTML character set for this document. The name
2617 should be a preferred MIME name as given in the IANA Registry @
2618 http://www.iana.org/assignments/character-sets. For example:
2619 % javadoc -charset "iso-8859-1" mypackage
2620 would insert the following line in the head of every generated
2621 page:
2622 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2623 This META tag is described in the HTML standard @
2624 http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2. (4197265
2625 and 4137321)
2626 Also see -encoding and -docencoding.
2627 -docencoding name
2629 Specifies the encoding of the generated HTML files. The name
2630 should be a preferred MIME name as given in the IANA Registry @
2631 http://www.iana.org/assignments/character-sets. If you omit this
2632 option but use -encoding, then the encoding of the generated HTML
2633 files is determined by -encoding. Example:
2634 % javadoc -docencoding "ISO-8859-1" mypackage
2635 Also see -encoding and -charset.
2636 -keywords
2638 Adds HTML meta keyword tags to the generated file for each class.
2639 These tags can help the page be found by search engines that look
2640 for meta tags. (Most search engines that search the entire Inter‐
2641 net do not look at meta tags, because pages can misuse them; but
2642 search engines offered by companies that confine their search to
2643 their own website can benefit by looking at meta tags.)
2644 The meta tags include the fully qualified name of the class and
2645 the unqualified names of the fields and methods. Constructors are
2646 not included because they are identical to the class name. For
2647 example, the class String starts with these keywords:
2648 <META NAME="keywords" CONTENT="java.lang.String class">
2649 <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
2650 <META NAME="keywords" CONTENT="length()">
2651 <META NAME="keywords" CONTENT="charAt()">
2652 -tag tagname:Xaoptcmf:"taghead"
2654 Enables the Javadoc tool to interpret a simple, one-argument cus‐
2655 tom block tag @tagname in doc comments. So the Javadoc tool can
2656 "spell-check" tag names, it is important to include a -tag option
2657 for every custom tag that is present in the source code, dis‐
2658 abling (with X) those that are not being output in the current
2659 run.
2660 The colon (:) is always the separator. To use a colon in tagname,
2661 see Use of Colon in Tag Name.
2662 The -tag option outputs the tag's heading taghead in bold, fol‐
2663 lowed on the next line by the text from its single argument, as
2664 shown in the example below. Like any block tag, this argument's
2665 text can contain inline tags, which are also interpreted. The
2666 output is similar to standard one-argument tags, such as @return
2667 and @author. Omitting taghead causes tagname to appear as the
2668 heading.
2669 Placement of tags - The Xaoptcmf part of the argument determines
2670 where in the source code the tag is allowed to be placed, and
2671 whether the tag can be disabled (using X). You can supply either
2672 a, to allow the tag in all places, or any combination of the
2673 other letters:
2674 X (disable tag)
2675 a (all)
2676 o (overview)
2677 p (packages)
2678 t (types, that is classes and interfaces)
2679 c (constructors)
2680 m (methods)
2681 f (fields)
2682 Examples of single tags - An example of a tag option for a tag
2683 that can be used anywhere in the source code is:
2684 -tag todo:a:"To Do:"
2685 If you wanted @todo to be used only with constructors, methods
2686 and fields, you would use:
2687 -tag todo:cmf:"To Do:"
2688 Notice the last colon (:) above is not a parameter separator, but
2689 is part of the heading text (as shown below). You would use
2690 either tag option for source code that contains the tag @todo,
2691 such as:
2692 @todo The documentation for this method needs work.
2693 Use of Colon in Tag Name - A colon can be used in a tag name if
2694 it is escaped with a backslash. For this doc comment:
2695 /**
2696 * @ejb:bean
2697 */
2698 use this tag option:
2699 -tag ejb\\:bean:a:"EJB Bean:"
2700 Spell-checking tag names (Disabling tags) - Some developers put
2701 custom tags in the source code that they don't always want to
2702 output. In these cases, it is important to list all tags that are
2703 present in the source code, enabling the ones you want to output
2704 and disabling the ones you don't want to output. The presence of
2705 X disables the tag, while its absence enables the tag. This gives
2706 the Javadoc tool enough information to know if a tag it encoun‐
2707 ters is unknown, probably the results of a typo or a misspelling.
2708 It prints a warning in these cases.
2709 You can add X to the placement values already present, so that
2710 when you want to enable the tag, you can simply delete the X. For
2711 example, if @todo is a tag that you want to suppress on output,
2712 you would use:
2713 -tag todo:Xcmf:"To Do:"
2714 or, if you'd rather keep it simple:
2715 -tag todo:X
2716 The syntax -tag todo:X works even if @todo is defined by a
2717 taglet.
2718 Order of tags - The order of the -tag (and -taglet) options
2719 determine the order the tags are output. You can mix the custom
2720 tags with the standard tags to intersperse them. The tag options
2721 for standard tags are placeholders only for determining the order
2722 -- they take only the standard tag's name. (Subheadings for stan‐
2723 dard tags cannot be altered.) This is illustrated in the follow‐
2724 ing example.
2725 If -tag is missing, then the position of -taglet determines its
2726 order. If they are both present, then whichever appears last on
2727 the command line determines its order. (This happens because the
2728 tags and taglets are processed in the order that they appear on
2729 the command line. For example, if -taglet and -tag both have the
2730 name "todo", the one that appears last on the command line will
2731 determine its order.
2732 Example of a complete set of tags - This example inserts "To Do"
2733 after "Parameters" and before "Throws" in the output. By using
2734 "X", it also specifies that @example is a tag that might be
2735 encountered in the source code that should not be output during
2736 this run. Notice that if you use @argfile, you can put the tags
2737 on separate lines in an argument file like this (no line continu‐
2738 ation characters needed):
2739 -tag param
2740 -tag return
2741 -tag todo:a:"To Do:"
2742 -tag throws
2743 -tag see
2744 -tag example:X
2745 When javadoc parses the doc comments, any tag encountered that is
2746 neither a standard tag nor passed in with -tag or -taglet is con‐
2747 sidered unknown, and a warning is thrown.
2748 The standard tags are initially stored internally in a list in
2749 their default order. Whenever -tag options are used, those tags
2750 get appended to this list -- standard tags are moved from their
2751 default position. Therefore, if a -tag option is omitted for a
2752 standard tag, it remains in its default position.
2753 Avoiding Conflicts - If you want to slice out your own namespace,
2754 you can use a dot-separated naming convention similar to that
2755 used for packages: com.mycompany.todo. Oracle will continue to
2756 create standard tags whose names do not contain dots. Any tag you
2757 create will override the behavior of a tag by the same name
2758 defined by Oracle. In other words, if you create a tag or taglet
2759 @todo, it will always have the same behavior you define, even if
2760 Oracle later creates a standard tag of the same name.
2761 Annotations vs. Javadoc Tags - In general, if the markup you want
2762 to add is intended to affect or produce documentation, it should
2763 probably be a javadoc tag; otherwise, it should be an annotation.
2764 See Comparing Annotations and Javadoc Tags @
2765 http://www.oracle.com/technetwork/java/javase/documenta‐
2766 tion/index-137868.html#annotations<
2767 You can also create more complex block tags, or custom inline
2768 tags with the -taglet option.
2769 -taglet class
2771 Specifies the class file that starts the taglet used in generat‐
2772 ing the documentation for that tag. Use the fully-qualified name
2773 for class. This taglet also defines the number of text arguments
2774 that the custom tag has. The taglet accepts those arguments, pro‐
2775 cesses them, and generates the output. For extensive documenta‐
2776 tion with example taglets, see:
2777 o Taglet Overview @
2779 http://docs.oracle.com/javase/7/docs/tech‐
2780 notes/guides/javadoc/taglet/overview.html
2781 Taglets are useful for block or inline tags. They can have any num‐
2782 ber of arguments and implement custom behavior, such as making text
2783 bold, formatting bullets, writing out the text to a file, or start‐
2784 ing other processes.
2785 Taglets can only determine where a tag should appear and in what
2786 form. All other decisions are made by the doclet. So a taglet cannot
2787 do things such as remove a class name from the list of included
2788 classes. However, it can execute side effects, such as printing the
2789 tag's text to a file or triggering another process.
2790 Use the -tagletpath option to specify the path to the taglet. Here
2791 is an example that inserts the "To Do" taglet after "Parameters" and
2792 ahead of "Throws" in the generated pages:
2793 -taglet com.sun.tools.doclets.ToDoTaglet
2794 -tagletpath /home/taglets
2795 -tag return
2796 -tag param
2797 -tag todo
2798 -tag throws
2799 -tag see
2800 Alternatively, you can use the -taglet option in place of its -tag
2801 option, but that may be harder to read.
2802 -tagletpath tagletpathlist
2804 Specifies the search paths for finding taglet class files
2805 (.class). The tagletpathlist can contain multiple paths by sepa‐
2806 rating them with a colon (:). The Javadoc tool will search in all
2807 subdirectories of the specified paths.
2808 -docfilessubdirs
2810 Enables deep copying of "doc-files" directories. In other words,
2811 subdirectories and all contents are recursively copied to the
2812 destination. For example, the directory doc-files/example/images
2813 and all its contents would now be copied. There is also an option
2814 to exclude subdirectories.
2815 -excludedocfilessubdir name1:name2...
2817 Excludes any "doc-files" subdirectories with the given names.
2818 This prevents the copying of SCCS and other source-code-control
2819 subdirectories.
2820 -noqualifier all | packagename1:packagename2:...
2822 Omits qualifying package name from ahead of class names in out‐
2823 put. The argument to -noqualifier is either "all" (all package
2824 qualifiers are omitted) or a colon-separate list of packages,
2825 with wildcards, to be removed as qualifiers. The package name is
2826 removed from places where class or interface names appear.
2827 The following example omits all package qualifiers:
2828 -noqualifier all
2829 The following example omits "java.lang" and "java.io" package
2830 qualifiers:
2831 -noqualifier java.lang:java.io
2832 The following example omits package qualifiers starting with
2833 "java", and "com.sun" subpackages (but not "javax"):
2834 -noqualifier java.*:com.sun.*
2835 Where a package qualifier would appear due to the above behavior,
2836 the name can be suitably shortened -- see How a name is dis‐
2837 played. This rule is in effect whether or not -noqualifier is
2838 used.
2839 -notimestamp
2841 Suppresses the timestamp, which is hidden in an HTML comment in
2842 the generated HTML near the top of each page. Useful when you
2843 want to run javadoc on two source bases and diff them, as it pre‐
2844 vents timestamps from causing a diff (which would otherwise be a
2845 diff on every page). The timestamp includes the javadoc version
2846 number, and currently looks like this:
2847 <!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->
2848 -nocomment
2850 Suppress the entire comment body, including the main description
2851 and all tags, generating only declarations. This option enables
2852 re-using source files originally intended for a different pur‐
2853 pose, to produce skeleton HTML documentation at the early stages
2854 of a new project.
2855 -sourcetab tabLength
2857 Specify the number of spaces each tab takes up in the source.
2858
2860 To shorten or simplify the javadoc command line, you can specify one or
2861 more files that themselves contain arguments to the javadoc command
2862 (except -J options). This enables you to create javadoc commands of any
2863 length on any operating system.
2864 An argument file can include javac options and source filenames in any
2866 combination. The arguments within a file can be space-separated or new‐
2867 line-separated. If a filename contains embedded spaces, put the whole
2868 filename in double quotes.
2869 Filenames within an argument file are relative to the current direc‐
2871 tory, not the location of the argument file. Wildcards (*) are not
2872 allowed in these lists (such as for specifying *.java). Use of the '@'
2873 character to recursively interpret files is not supported. The -J
2874 options are not supported because they are passed to the launcher,
2875 which does not support argument files.
2876 When executing javadoc, pass in the path and name of each argument file
2878 with the '@' leading character. When javadoc encounters an argument
2879 beginning with the character `@', it expands the contents of that file
2880 into the argument list.
2881 Example - Single Arg File
2883 You could use a single argument file named "argfile" to hold all
2884 Javadoc arguments:
2885 % javadoc @argfile
2886 This argument file could contain the contents of both files shown in
2888 the next example.
2889 Example - Two Arg Files
2891 You can create two argument files -- one for the Javadoc options and
2892 the other for the package names or source filenames: (Notice the fol‐
2893 lowing lists have no line-continuation characters.)
2894 Create a file named "options" containing:
2896 -d docs-filelist
2897 -use
2898 -splitindex
2899 -windowtitle 'Java SE 7 API Specification'
2900 -doctitle 'Java SE 7 API Specification'
2901 -header '<b>Java(TM) SE 7</b>'
2902 -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.'
2903 -group "Core Packages" "java.*"
2904 -overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html
2905 -sourcepath /java/pubs/ws/1.7.0/src/share/classes
2906 Create a file named "packages" containing:
2908 com.mypackage1
2909 com.mypackage2
2910 com.mypackage3
2911 You would then run javadoc with:
2913 % javadoc @options @packages
2914 Example - Arg Files with Paths
2916 The argument files can have paths, but any filenames inside the files
2917 are relative to the current working directory (not path1 or path2):
2918 % javadoc @path1/options @path2/packages
2919 Example - Option Arguments
2921 Here's an example of saving just an argument to a javadoc option in an
2922 argument file. We'll use the -bottom option, since it can have a
2923 lengthy argument. You could create a file named "bottom" containing its
2924 text argument:
2925 <font size="-1">
2926 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
2927 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
2928 Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
2929 Other names may be trademarks of their respective owners.</font>
2930 Then run the Javadoc tool with:
2932 % javadoc -bottom @bottom @packages
2933 Or you could include the -bottom option at the start of the argument
2935 file, and then just run it as:
2936 % javadoc @bottom @packages
2937
2939 Running
2940
2942 Version Numbers - The version number of javadoc can be determined using
2943 javadoc -J-version. The version number of the standard doclet appears
2944 in its output stream. It can be turned off with -quiet.
2945 Public programmatic interface - To invoke the Javadoc tool from within
2947 programs written in the Java language. This interface is in
2948 com.sun.tools.javadoc.Main (and javadoc is re-entrant). For more
2949 details, see Standard Doclet @
2950 http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/stan‐
2951 dard-doclet.html#runningprogrammatically.
2952 Running Doclets - The instructions given below are for invoking the
2954 standard HTML doclet. To invoke a custom doclet, use the -doclet and
2955 -docletpath options. For full, working examples of running a particular
2956 doclet, see the MIF Doclet documentation @
2957 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
2958
2960 You can run javadoc on entire packages or individual source files. Each
2961 package name has a corresponding directory name. In the following exam‐
2962 ples, the source files are located at /home/src/java/awt/*.java. The
2963 destination directory is /home/html.
2964 Documenting One or More Packages
2966 To document a package, the source files (*.java) for that package must
2967 be located in a directory having the same name as the package. If a
2968 package name is made up of several identifiers (separated by dots, such
2969 as java.awt.color), each subsequent identifier must correspond to a
2970 deeper subdirectory (such as java/awt/color). You may split the source
2971 files for a single package among two such directory trees located at
2972 different places, as long as -sourcepath points to them both -- for
2973 example src1/java/awt/color and src2/java/awt/color.
2974 You can run javadoc either by changing directories (with cd) or by
2976 using -sourcepath option. The examples below illustrate both alterna‐
2977 tives.
2978 o Case 1 - Run recursively starting from one or more packages - This
2980 example uses -sourcepath so javadoc can be run from any directory
2981 and -subpackages (a new 1.4 option) for recursion. It traverses
2982 the subpackages of the java directory excluding packages rooted at
2983 java.net and java.lang. Notice this excludes java.lang.ref, a sub‐
2984 package of java.lang).
2985 % javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang
2986 To also traverse down other package trees, append their names to the
2988 -subpackages argument, such as java:javax:org.xml.sax.
2989 o Case 2 - Run on explicit packages after changing to the "root"
2991 source directory - Change to the parent directory of the
2992 fully-qualified package. Then run javadoc, supplying names of one
2993 or more packages you want to document:
2994 % cd /home/src/
2995 % javadoc -d /home/html java.awt java.awt.event
2996 o Case 3 - Run from any directory on explicit packages in a single
2998 directory tree - In this case, it doesn't matter what the current
2999 directory is. Run javadoc supplying -sourcepath with the parent
3000 directory of the top-level package, and supplying names of one or
3001 more packages you want to document:
3002 % javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
3003 o Case 4 - Run from any directory on explicit packages in multiple
3005 directory trees - This is the same as case 3, but for packages in
3006 separate directory trees. Run javadoc supplying -sourcepath with
3007 the path to each tree's root (colon-separated) and supply names of
3008 one or more packages you want to document. All source files for a
3009 given package do not need to be located under a single root direc‐
3010 tory -- they just need to be found somewhere along the sourcepath.
3011 % javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
3012 Result: All cases generate HTML-formatted documentation for the public
3014 and protected classes and interfaces in packages java.awt and
3015 java.awt.event and save the HTML files in the specified destination
3016 directory (/home/html). Because two or more packages are being gener‐
3017 ated, the document has three HTML frames -- for the list of packages,
3018 the list of classes, and the main class pages.
3019 Documenting One or More Classes
3021 The second way to run the Javadoc tool is by passing in one or more
3022 source files (.java). You can run javadoc either of the following two
3023 ways -- by changing directories (with cd) or by fully-specifying the
3024 path to the .java files. Relative paths are relative to the current
3025 directory. The -sourcepath option is ignored when passing in source
3026 files. You can use command line wildcards, such as asterisk (*), to
3027 specify groups of classes.
3028 o Case 1 - Changing to the source directory - Change to the direc‐
3030 tory holding the .java files. Then run javadoc, supplying names of
3031 one or more source files you want to document.
3032 % cd /home/src/java/awt
3033 % javadoc -d /home/html Button.java Canvas.java Graphics*.java
3034 This example generates HTML-formatted documentation for the
3035 classes Button, Canvas and classes beginning with Graphics.
3036 Because source files rather than package names were passed in as
3037 arguments to javadoc, the document has two frames -- for the list
3038 of classes and the main page.
3039 o Case 2 - Changing to the package root directory - This is useful
3041 for documenting individual source files from different subpackages
3042 off the same root. Change to the package root directory, and sup‐
3043 ply the source files with paths from the root.
3044 % cd /home/src/
3045 % javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
3046 This example generates HTML-formatted documentation for the
3047 classes Button and Applet.
3048 o Case 3 - From any directory - In this case, it doesn't matter what
3050 the current directory is. Run javadoc supplying the absolute path
3051 (or path relative to the current directory) to the .java files you
3052 want to document.
3053 % javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
3054 This example generates HTML-formatted documentation for the class
3055 Button and classes beginning with Graphics.
3056 Documenting Both Packages and Classes
3058 You can document entire packages and individual classes at the same
3059 time. Here's an example that mixes two of the previous examples. You
3060 can use -sourcepath for the path to the packages but not for the path
3061 to the individual classes.
3062 % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java
3063 This example generates HTML-formatted documentation for the package
3065 java.awt and class Applet. (The Javadoc tool determines the package
3066 name for Applet from the package declaration, if any, in the
3067 Applet.java source file.)
3068
3070 The Javadoc tool has many useful options, some of which are more com‐
3071 monly used than others. Here is effectively the command we use to run
3072 the Javadoc tool on the Java platform API. We use 180MB of memory to
3073 generate the documentation for the 1500 (approx.) public and protected
3074 classes in the Java SE Platform, Standard Edition, v1.2.
3075 The same example is shown twice -- first as executed on the command
3077 line, then as executed from a makefile. It uses absolute paths in the
3078 option arguments, which enables the same javadoc command to be run from
3079 any directory.
3080 Command Line Example
3082 The following example may be too long for some shells such as DOS. You
3083 can use a command line argument file (or write a shell script) to work‐
3084 around this limitation.
3085 % javadoc -sourcepath /java/jdk/src/share/classes \
3086 -overview /java/jdk/src/share/classes/overview.html \
3087 -d /java/jdk/build/api \
3088 -use \
3089 -splitIndex \
3090 -windowtitle 'Java Platform, Standard Edition 7 API Specification' \
3091 -doctitle 'Java Platform, Standard Edition 7 API Specification' \
3092 -header '<b>Java(TM) SE 7</b>' \
3093 -bottom '<font size="-1">
3094 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
3095 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
3096 Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
3097 Other names may be trademarks of their respective owners.</font>' \
3098 -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
3099 -group "Extension Packages" "javax.*" \
3100 -J-Xmx180m \
3101 @packages
3102 where packages is the name of a file containing the packages to
3104 process, such as java.applet java.lang. None of the options should con‐
3105 tain any newline characters between the single quotes. (For example, if
3106 you copy and paste this example, delete the newline characters from the
3107 -bottom option.) See the other notes listed below.
3108 Makefile Example
3110 This is an example of a GNU makefile. For an example of a Windows make‐
3111 file, see creating a makefile for Windows @
3112 http://java.sun.com/j2se/javadoc/faq/index.html#makefiles.
3113 javadoc -sourcepath $(SRCDIR) \ /* Sets path for source files */
3114 -overview $(SRCDIR)/overview.html \ /* Sets file for overview text */
3115 -d /java/jdk/build/api \ /* Sets destination directory */
3116 -use \ /* Adds "Use" files */
3117 -splitIndex \ /* Splits index A-Z */
3118 -windowtitle $(WINDOWTITLE) \ /* Adds a window title */
3119 -doctitle $(DOCTITLE) \ /* Adds a doc title */
3120 -header $(HEADER) \ /* Adds running header text */
3121 -bottom $(BOTTOM) \ /* Adds text at bottom */
3122 -group $(GROUPCORE) \ /* 1st subhead on overview page */
3123 -group $(GROUPEXT) \ /* 2nd subhead on overview page */
3124 -J-Xmx180m \ /* Sets memory to 180MB */
3125 java.lang java.lang.reflect \ /* Sets packages to document */
3126 java.util java.io java.net \
3127 java.applet
3128 WINDOWTITLE = 'Java(TM) SE 7 API Specification'
3130 DOCTITLE = 'Java(TM) Platform Standard Edition 7 API Specification'
3131 HEADER = '<b>Java(TM) SE 7</font>'
3132 BOTTOM = '<font size="-1">
3133 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
3134 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
3135 Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
3136 Other names may be trademarks of their respective owners.</font>'
3137 GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
3138 GROUPEXT = '"Extension Packages" "javax.*"'
3139 SRCDIR = '/java/jdk/1.7.0/src/share/classes'
3140 Single quotes are used to surround makefile arguments.
3142 NOTES
3144 o If you omit the -windowtitle option, the Javadoc tool copies the
3146 doc title to the window title. The -windowtitle text is basically
3147 the same as the -doctitle but without HTML tags, to prevent those
3148 tags from appearing as raw text in the window title.
3149 o If you omit the -footer option, as done here, the Javadoc tool
3151 copies the header text to the footer.
3152 o Other important options you might want to use but not needed in
3154 this example are -classpath and -link.
3155
3157 General Troubleshooting
3158 o Javadoc FAQ - Commonly-encountered bugs and troubleshooting tips
3159 can be found on the Javadoc FAQ @
3160 http://java.sun.com/j2se/javadoc/faq/index.html#B
3161 o Bugs and Limitations - You can also see some bugs listed at Impor‐
3163 tant Bug Fixes and Changes.
3164 o Version number - See version numbers.
3166 o Documents only legal classes - When documenting a package, javadoc
3168 only reads files whose names are composed of legal class names.
3169 You can prevent javadoc from parsing a file by including, for
3170 example, a hyphen "-" in its filename.
3171 Errors and Warnings
3173 Error and warning messages contain the filename and line number to the
3174 declaration line rather than to the particular line in the doc comment.
3175 o "error: cannot read: Class1.java" the Javadoc tool is trying to
3177 load the class Class1.java in the current directory. The class
3178 name is shown with its path (absolute or relative), which in this
3179 case is the same as ./Class1.java.
3180
3182 CLASSPATH
3183 Environment variable that provides the path which javadoc uses to
3184 find user class files. This environment variable is overridden by
3185 the -classpath option. Separate directories with a colon, for
3186 example:
3187
3189 o javac(1)
3190 o java(1)
3192 o jdb(1)
3194 o javah(1)
3196 o javap(1)
3198 o Javadoc Home Page @
3200 http://www.oracle.com/technetwork/java/javase/documenta‐
3201 tion/index-jsp-135444.html
3202 o How to Write Doc Comments for Javadoc @
3204 http://www.oracle.com/technetwork/java/javase/documenta‐
3205 tion/index-137868.html
3206 o Setting the Class Path @
3208 http://docs.oracle.com/javase/7/docs/tech‐
3209 notes/tools/index.html#general
3210 o How Javac and Javadoc Find Classes @
3212 http://docs.oracle.com/javase/7/docs/technotes/tools/finding‐
3213 classes.html#srcfiles (tools.jar)
3214 16 Mar 2012 javadoc(1)