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.
10 This document contains Javadoc examples for Sun Solaris.
11
13 javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpack‐
14 ages pkg1:pkg2:... ] [ @argfiles ]
15 Arguments can be in any order. See processing of Source Files for
17 details on how the Javadoc tool determines which ".java" files to
18 process.
19 options
21 Command-line options, as specified in this document. To see a
22 typical use of javadoc options, see Real-World Example.
23 packagenames
25 A series of names of packages, separated by spaces, such as
26 java.lang java.lang.reflect java.awt. You must separately
27 specify each package you want to document. Wildcards are not
28 allowed; use -subpackages for recursion. The Javadoc tool uses
29 -sourcepath to look for these package names. See Example -
30 Documenting One or More Packages
31 sourcefilenames
33 A series of source file names, separated by spaces, each of
34 which can begin with a path and contain a wildcard such as
35 asterisk (*). The Javadoc tool will process every file whose
36 name ends with ".java", and whose name, when stripped of that
37 suffix, is actually a legal class name (see Identifiers @
38 http://java.sun.com/docs/books/jls/second_edition/html/lexi‐
39 cal.doc.html#40625). Therefore, you can name files with dashes
40 (such as X-Buffer), or other illegal characters, to prevent
41 them from being documented. This is useful for test files and
42 template files The path that precedes the source file name
43 determines where javadoc will look for the file. (The Javadoc
44 tool does not use -sourcepath to look for these source file
45 names.) Relative paths are relative to the current directory,
46 so passing in Button.java is identical to ./Button.java. A
47 source file name with an absolute path and a wildcard, for
48 example, is /home/src/java/awt/Graphics*.java. See Exam‐
49 ple - Documenting One or More Classes. You can also mix packa‐
50 genames and sourcefilenames, as in Example - Documenting Both
51 Packages and Classes
52 -subpackages pkg1:pkg2:...
54 Generates documentation from source files in the specified
55 packages and recursively in their subpackages. An alternative
56 to supplying packagenames or sourcefilenames.
57 @argfiles
59 One or more files that contain a list of Javadoc options,
60 packagenames and sourcefilenames in any order. Wildcards (*)
61 and -J options are not allowed in these files.
62
65 The Javadoc tool parses the declarations and documentation comments in
66 a set of Java source files and produces a corresponding set of HTML
67 pages describing (by default) the public and protected classes, nested
68 classes (but not anonymous inner classes), interfaces, constructors,
69 methods, and fields. You can use it to generate the API (Application
70 Programming Interface) documentation or the implementation documenta‐
71 tion for a set of source files.
72 You can run the Javadoc tool on entire packages, individual source
74 files, or both. When documenting entire packages, you can either use
75 -subpackages for traversing recursively down from a top-level direc‐
76 tory, or pass in an explicit list of package names. When documenting
77 individual source files, you pass in a list of source (.java) file‐
78 names. Examples are given at the end of this document. How Javadoc pro‐
79 cesses source files is covered next.
80 Processing of source files
82 The Javadoc tool processes files that end in ".java" plus other files
83 described under Source Files. If you run the Javadoc tool by explicitly
84 passing in individual source filenames, you can determine exactly which
85 ".java" files are processed. However, that is not how most developers
86 want to work, as it is simpler to pass in package names. The Javadoc
87 tool can be run three ways without explicitly specifying the source
88 filenames. You can (1) pass in package names, (2) use -subpackages, and
89 (3) use wildcards with source filenames (*.java). In these cases, the
90 Javadoc tool processes a ".java" file only if it fulfills all of the
91 following requirements:
92 o Its name, after stripping off the ".java" suffix, is actually a
94 legal class name (see Identifiers @
95 http://java.sun.com/docs/books/jls/second_edition/html/lexi‐
96 cal.doc.html#40625 for legal characters)
97 o Its directory path relative to the root of the source tree is
99 actually a legal package name (after converting its separators to
100 dots)
101 o Its package statement contains the legal package name (specified
103 in the previous bullet)
104 Processing of links - During a run, the Javadoc tool automatically adds
107 cross-reference links to package, class and member names that are being
108 documented as part of that run. Links appear in several places:
109 o Declarations (return types, argument types, field types)
111 o "See Also" sections generated from @see tags
113 o In-line text generated from {@link} tags
115 o Exception names generated from @throws tags
117 o "Specified by" links to members in interfaces and "Overrides"
119 links to members in classes
120 o Summary tables listing packages, classes and members
122 o Package and class inheritance trees
124 o The index
126 You can add hyperlinks to existing text for classes not included on the
129 command line (but generated separately) by way of the -link and
130 -linkoffline options.
131 Other processing details - The Javadoc tool produces one complete docu‐
133 ment each time it is run; it cannot do incremental builds -- that is,
134 it cannot modify or directly incorporate results from previous runs of
135 the Javadoc tool. However, it can link to results from other runs, as
136 just mentioned.
137 As implemented, the Javadoc tool requires and relies on the java com‐
139 piler to do its job. The Javadoc tool calls part of javac to compile
140 the declarations, ignoring the member implementation. It builds a rich
141 internal representation of the classes, including the class hierarchy,
142 and "use" relationships, then generates the HTML from that. The Javadoc
143 tool also picks up user-supplied documentation from documentation com‐
144 ments in the source code.
145 In fact, the Javadoc tool will run on .java source files that are pure
147 stub files with no method bodies. This means you can write documenta‐
148 tion comments and run the Javadoc tool in the earliest stages of design
149 while creating the API, before writing the implementation.
150 Relying on the compiler ensures that the HTML output corresponds
152 exactly with the actual implementation, which may rely on implicit,
153 rather than explicit, source code. For example, the Javadoc tool docu‐
154 ments default constructors @
155 http://java.sun.com/docs/books/jls/second_edi‐
156 tion/html/names.doc.html#36154 (section 8.6.7 of Java Language Specifi‐
157 cation) that are present in the .class files but not in the source
158 code.
159 In many cases, the Javadoc tool allows you to generate documentation
161 for source files whose code is incomplete or erroneous. This is a bene‐
162 fit that enables you to generate documentation before all debugging and
163 troubleshooting is done. For example, according to the Java Language
164 Specification, a class that contains an abstract method should itself
165 be declared abstract. The Javadoc tool does not check for this, and
166 would proceed without a warning, whereas the javac compiler stops on
167 this error. The Javadoc tool does do some primitive checking of doc
168 comments. Use the DocCheck doclet to check the doc comments more thor‐
169 oughly.
170 When the Javadoc tool builds its internal structure for the documenta‐
172 tion, it loads all referenced classes. Because of this, the Javadoc
173 tool must be able to find all referenced classes, whether bootstrap
174 classes, extensions, or user classes. For more about this, see How
175 Classes Are Found. Generally speaking, classes you create must either
176 be loaded as an extension or in the Javadoc tool's class path.
177 Javadoc Doclets
179 You can customize the content and format of the Javadoc tool's output
180 by using doclets. The Javadoc tool has a default "built-in" doclet,
181 called the standard doclet, that generates HTML-formatted API documen‐
182 tation. You can modify or subclass the standard doclet, or write your
183 own doclet to generate HTML, XML, MIF, RTF or whatever output format
184 you'd like. Information about doclets and their use is at the following
185 locations:
186 o Javadoc Doclets
188 o The -doclet command-line option
190 When a custom doclet is not specified with the -doclet command line
193 option, the Javadoc tool will use the default standard doclet. The
194 javadoc tool has several command line options that are available
195 regardless of which doclet is being used. The standard doclet adds a
196 supplementary set of command line options. Both sets of options are
197 described below in the options section.
198 Related Documentation and Doclets
200 o Javadoc Enhancements for details about improvements added in
201 Javadoc.
202 o Javadoc FAQ @
204 http://java.sun.com/j2se/javadoc/faq/index.html for answers to
205 common questions, information about Javadoc-related tools, and
206 workarounds for bugs.
207 o How to Write Doc Comments for Javadoc @
209 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html for
210 more information about Sun conventions for writing documentation
211 comments.
212 o Requirements for Writing API Specifications @
214 http://java.sun.com/j2se/javadoc/writingapispecs/index.html -
215 Standard requirements used when writing the Java 2 Platform Speci‐
216 fication. It can be useful whether you are writing API specifica‐
217 tions in source file documentation comments or in other formats.
218 It covers requirements for packages, classes, interfaces, fields
219 and methods to satisfy testable assertions.
220 o Documentation Comment Specification @
222 http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html
223 - The original specification on documentation comments, Chapter
224 18, Documentation Comments, in the Java Language Specification,
225 First Edition, by James Gosling, Bill Joy, and Guy Steele. (This
226 chapter was removed from the second edition.)
227 o DocCheck Doclet @
229 http://java.sun.com/javadoc/doccheck - Checks doc comments in
230 source files and generates a report listing the errors and irregu‐
231 larities it finds. It is part of the Sun Doc Check Utilities.
232 o MIF Doclet @
234 http://java.sun.com/javadoc/mifdoclet - Can automate the genera‐
235 tion of API documentation in MIF, FrameMaker and PDF formats. MIF
236 is Adobe FrameMaker's interchange format.
237 Terminology
240 The terms documentation comment, doc comment, main description, tag,
241 block tag, and in-line tag are described at Documentation Comments.
242 These other terms have specific meanings within the context of the
243 Javadoc tool:
244 generated document
246 The document generated by the javadoc tool from the doc comments
247 in Java source code. The default generated document is in HTML
248 and is created by the standard doclet.
249 name
251 A name of a program element written in the Java Language -- that
252 is, the name of a package, class, interface, field, constructor
253 or method. A name can be fully-qualified, such as
254 java.lang.String.equals(java.lang.Object), or partially-quali‐
255 fied, such as equals(Object).
256 documented classes
258 The classes and interfaces for which detailed documentation is
259 generated during a javadoc run. To be documented, the source
260 files must be available, their source filenames or package names
261 must be passed into the javadoc command, and they must not be
262 filtered out by their access modifier (public, protected, pack‐
263 age-private or private). We also refer to these as the classes
264 included in the javadoc output, or the included classes.
265 included classes
267 Classes and interfaces whose details are documented during a run
268 of the Javadoc tool. Same as documented classes.
269 excluded classes
271 Classes and interfaces whose details are not documented during a
272 run of the Javadoc tool.
273 referenced classes
275 The classes and interfaces that are explicitly referred to in the
276 definition (implementation) or doc comments of the documented
277 classes and interfaces. Examples of references include return
278 type, parameter type, cast type, extended class, implemented
279 interface, imported classes, classes used in method bodies, @see,
280 {@link}, {@linkplain}, and {@inheritDoc} tags. (Notice this defi‐
281 nition has changed since 1.3 @
282 http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#ref‐
283 erencedclasses.) When the Javadoc tool is run, it should load
284 into memory all of the referenced classes in javadoc's bootclass‐
285 path and classpath. (The Javadoc tool prints a "Class not found"
286 warning for referenced classes not found.) The Javadoc tool can
287 derive enough information from the .class files to determine
288 their existence and the fully-qualified names of their members.
289 external referenced classes
291 The referenced classes whose documentation is not being generated
292 during a javadoc run. In other words, these classes are not
293 passed into the Javadoc tool on the command line. Links in the
294 generated documentation to those classes are said to be external
295 references or external links. For example, if you run the Javadoc
296 tool on only the java.awt package, then any class in java.lang,
297 such as Object, is an external referenced class. External refer‐
298 enced classes can be linked to using the -link and -linkoffline
299 options. An important property of an external referenced class is
300 that its source comments are normally not available to the
301 Javadoc run. In this case, these comments cannot be inherited.
302
305 The Javadoc tool will generate output originating from four different
306 types of "source" files: Java language source files for classes
307 (.java), package comment files, overview comment files, and miscella‐
308 neous unprocessed files. This section also covers test files and tem‐
309 plate files that can also be in the source tree, but which you want to
310 be sure not to document.
311 Class Source Code Files
313 Each class or interface and its members can have their own documenta‐
314 tion comments, contained in a .java file. For more details about these
315 doc comments, see Documentation Comments.
316 Package Comment Files
318 Each package can have its own documentation comment, contained in its
319 own "source" file, that the Javadoc tool will merge into the package
320 summary page that it generates. You typically include in this comment
321 any documentation that applies to the entire package.
322 To create a package comment file, you have a choice of two files to
324 place your comments:
325 o package-info.java - Can contain a package declaration, package
327 annotations, package comments and Javadoc tags. This file is new
328 in JDK 5.0, and is preferred over package.html.
329 o package.html - Can contain only package comments and Javadoc tags,
331 no package annotations.
332 A package may have a single package.html file or a single pack‐
335 age-info.java file but not both. Place either file in the package
336 directory in the source tree along with your .java files.
337 package-info.java This file can contain a package comment of the fol‐
339 lowing structure -- the comment is placed before the package declara‐
340 tion:
341 File: java/applet/package-info.java
343 Note that while the comment separators /** and /* must be present, the
345 leading asterisks on the intermediate lines can be omitted.
346 package.html - This file can contain a package comment of the following
348 structure -- the comment is placed in the <body> element:
349 File: java/applet/package.html
351 Notice this is just a normal HTML file and does not include a package
353 declaration. The content of the package comment file is written in
354 HTML, like all other comments, with one exception: The documentation
355 comment should not include the comment separators /** and */ or leading
356 asterisks. When writing the comment, you should make the first sentence
357 a summary about the package, and not put a title or any other text
358 between <body> and the first sentence. You can include package tags; as
359 with any documentation comment, all block tags must appear after the
360 main description. If you add a @see tag in a package comment file, it
361 must have a fully-qualified name. For more details, see the example of
362 package.html @
363 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#pack‐
364 agecomments.
365 Processing of package comment file - When the Javadoc tool runs, it
367 will automatically look for the package comment file; if found, the
368 Javadoc tool does the following:
369 o Copies the comment for processing. (For package.html, copies all
371 content between <body> and </body> HTML tags. You can include a
372 <head> section to put a <title>, source file copyright statement,
373 or other information, but none of these will appear in the gener‐
374 ated documentation.)
375 o Processes any package tags that are present.
377 o Inserts the processed text at the bottom of the package summary
379 page it generates, as shown in Package Summary.
380 o Copies the first sentence of the package comment to the top of the
382 package summary page. It also adds the package name and this first
383 sentence to the list of packages on the overview page, as shown in
384 Overview Summary. The end-of-sentence is determined by the same
385 rules used for the end of the first sentence of class and member
386 main descriptions.
387 Overview Comment File
390 Each application or set of packages that you are documenting can have
391 its own overview documentation comment, kept in its own "source" file,
392 that the Javadoc tool will merge into the overview page that it gener‐
393 ates. You typically include in this comment any documentation that
394 applies to the entire application or set of packages.
395 To create an overview comment file, you can name the file anything you
397 want, typically overview.html and place it anywhere, typically at the
398 top level of the source tree. For example, if the source files for the
399 java.applet package are contained in /home/user/src/java/applet direc‐
400 tory, you could create an overview comment file at /home/user/src/over‐
401 view.html.
402 Notice you can have multiple overview comment files for the same set of
404 source files, in case you want to run javadoc multiple times on differ‐
405 ent sets of packages. For example, you could run javadoc once with
406 -private for internal documentation and again without that option for
407 public documentation. In this case, you could describe the documenta‐
408 tion as public or internal in the first sentence of each overview com‐
409 ment file.
410 The content of the overview comment file is one big documentation com‐
412 ment, written in HTML, like the package comment file described previ‐
413 ously. See that description for details. To re-iterate, when writing
414 the comment, you should make the first sentence a summary about the
415 application or set of packages, and not put a title or any other text
416 between <body> and the first sentence. You can include overview tags;
417 as with any documentation comment, all tags except in-line tags, such
418 as {@link}, must appear after the main description. If you add a @see
419 tag, it must have a fully-qualified name.
420 When you run the Javadoc tool, you specify the overview comment file
422 name with the -overview option. The file is then processed similar to
423 that of a package comment file.
424 o Copies all content between <body> and </body> tags for processing.
426 o Processes any overview tags that are present.
428 o Inserts the processed text at the bottom of the overview page it
430 generates, as shown in Overview Summary.
431 o Copies the first sentence of the overview comment to the top of
433 the overview summary page.
434 Miscellaneous Unprocessed Files
437 You can also include in your source any miscellaneous files that you
438 want the Javadoc tool to copy to the destination directory. These typi‐
439 cally includes graphic files, example Java source (.java) and class
440 (.class) files, and self-standing HTML files whose content would over‐
441 whelm the documentation comment of a normal Java source file.
442 To include unprocessed files, put them in a directory called doc-files
444 which can be a subdirectory of any package directory that contains
445 source files. You can have one such subdirectory for each package. You
446 might include images, example code, source files, .class files, applets
447 and HTML files. For example, if you want to include the image of a but‐
448 ton button.gif in the java.awt.Button class documentation, you place
449 that file in the /home/user/src/java/awt/doc-files/ directory. Notice
450 the doc-files directory should not be located at
451 /home/user/src/java/doc-files because java is not a package -- that is,
452 it does not directly contain any source files.
453 All links to these unprocessed files must be hard-coded, because the
455 Javadoc tool does not look at the files -- it simply copies the direc‐
456 tory and all its contents to the destination. For example, the link in
457 the Button.java doc comment might look like:
458 /**
460 * This button looks like this:
461 * <img src="doc-files/Button.gif">
462 */
463 Test Files and Template Files
466 Some developers have indicated they want to store test files and tem‐
467 plates files in the source tree near their corresponding source files.
468 That is, they would like to put them in the same directory, or a subdi‐
469 rectory, of those source files.
470 If you run the Javadoc tool by explicitly passing in individual source
472 filenames, you can deliberately omit test and templates files and pre‐
473 vent them from being processed. However, if you are passing in package
474 names or wildcards, you need to follow certain rules to ensure these
475 test files and templates files are not processed.
476 Test files differ from template files in that the former are legal,
478 compilable source files, while the latter are not, but may end with
479 ".java".
480 Test files - Often developers want to put compilable, runnable test
482 files for a given package in the same directory as the source files for
483 that package. But they want the test files to belong to a package other
484 than the source file package, such as the unnamed package (so the test
485 files have no package statement or a different package statement from
486 the source). In this scenario, when the source is being documented by
487 specifying its package name specified on the command line, the test
488 files will cause warnings or errors. You need to put such test files in
489 a subdirectory. For example, if you want to add test files for source
490 files in com.package1, put them in a subdirectory that would be an
491 invalid package name (because it contains a hyphen):
492 com/package1/test-files/
494 The test directory will be skipped by the Javadoc tool with no warn‐
497 ings.
498 If your test files contain doc comments, you can set up a separate run
500 of the Javadoc tool to produce documentation of the test files by pass‐
501 ing in their test source filenames with wildcards, such as com/pack‐
502 age1/test-files/*.java.
503 Templates for source files - Template files have names that often end
505 in ".java" and are not compilable. If you have a template for a source
506 file that you want to keep in the source directory, you can name it
507 with a dash (such as Buffer-Template.java), or any other illegal Java
508 character, to prevent it from being processed. This relies on the fact
509 that the Javadoc tool will only process source files whose name, when
510 stripped of the ".java" suffix, is actually a legal class name (see
511 Identifiers @
512 http://java.sun.com/docs/books/jls/second_edition/html/lexi‐
513 cal.doc.html#40625).
514
516 By default, javadoc uses a standard doclet that generates HTML-format‐
517 ted documentation. This doclet generates the following kinds of files
518 (where each HTML "page" corresponds to a separate file). Note that
519 javadoc generates files with two types of names: those named after
520 classes/interfaces, and those that are not (such as package-sum‐
521 mary.html). Files in the latter group contain hyphens to prevent file‐
522 name conflicts with those in the former group.
523 Basic Content Pages
525 o One class or interface page (classname.html) for each class or
527 interface it is documenting.
528 o One package page (package-summary.html) for each package it is
530 documenting. The Javadoc tool will include any HTML text provided
531 in a file named package.html or package-info.java in the package
532 directory of the source tree.
533 o One overview page (overview-summary.html) for the entire set of
535 packages. This is the front page of the generated document. The
536 Javadoc tool will include any HTML text provided in a file speci‐
537 fied with the -overview option. Note that this file is created
538 only if you pass into javadoc two or more package names. For fur‐
539 ther explanation, see HTML Frames.)
540 Cross-Reference Pages
543 o One class hierarchy page for the entire set of packages (over‐
545 view-tree.html). To view this, click on "Overview" in the naviga‐
546 tion bar, then click on "Tree".
547 o One class hierarchy page for each package (package-tree.html) To
549 view this, go to a particular package, class or interface page;
550 click "Tree" to display the hierarchy for that package.
551 o One "use" page for each package (package-use.html) and a separate
553 one for each class and interface (class-use/classname.html). This
554 page describes what packages, classes, methods, constructors and
555 fields use any part of the given class, interface or package.
556 Given a class or interface A, its "use" page includes subclasses
557 of A, fields declared as A, methods that return A, and methods and
558 constructors with parameters of type A. You can access this page
559 by first going to the package, class or interface, then clicking
560 on the "Use" link in the navigation bar.
561 o A deprecated API page (deprecated-list.html) listing all depre‐
563 cated names. (A deprecated name is not recommended for use, gener‐
564 ally due to improvements, and a replacement name is usually given.
565 Deprecated APIs may be removed in future implementations.)
566 o A constant field values page (constant-values.html) for the values
568 of static fields.
569 o A serialized form page (serialized-form.html) for information
571 about serializable and externalizable classes. Each such class has
572 a description of its serialization fields and methods. This infor‐
573 mation is of interest to re-implementors, not to developers using
574 the API. While there is no link in the navigation bar, you can get
575 to this information by going to any serialized class and clicking
576 "Serialized Form" in the "See also" section of the class comment.
577 The standard doclet automatically generates a serialized form
578 page: any class (public or non-public) that implements Serializ‐
579 able is included, along with readObject and writeObject methods,
580 the fields that are serialized, and the doc comments from the
581 @serial, @serialField, and @serialData tags. Public serializable
582 classes can be excluded by marking them (or their package) with
583 @serial exclude, and package-private serializable classes can be
584 included by marking them (or their package) with @serial include.
585 As of 1.4, you can generate the complete serialized form for pub‐
586 lic and private classes by running javadoc without specifying the
587 -private option.
588 o An index (index-*.html) of all class, interface, constructor,
590 field and method names, alphabetically arranged. This is interna‐
591 tionalized for Unicode and can be generated as a single file or as
592 a separate file for each starting character (such as A-Z for Eng‐
593 lish).
594 Support Files
597 o A help page (help-doc.html) that describes the navigation bar and
599 the above pages. You can provide your own custom help file to
600 override the default using -helpfile.
601 o One index.html file which creates the HTML frames for display.
603 This is the file you load to display the front page with frames.
604 This file itself contains no text content.
605 o Several frame files (*-frame.html) containing lists of packages,
607 classes and interfaces, used when HTML frames are being displayed.
608 o A package list file (package-list), used by the -link and -linkof‐
610 fline options. This is a text file, not HTML, and is not reachable
611 through any links.
612 o A style sheet file (stylesheet.css) that controls a limited amount
614 of color, font family, font size, font style and positioning on
615 the generated pages.
616 o A doc-files directory that holds any image, example, source code
618 or other files that you want copied to the destination directory.
619 These files are not processed by the Javadoc tool in any manner --
620 that is, any javadoc tags in them will be ignored. This directory
621 is not generated unless it exists in the source tree.
622 HTML Frames
625 The Javadoc tool will generate either two or three HTML frames, as
627 shown in the figure below. It creates the minimum necessary number of
628 frames by omitting the list of packages if there is only one package
629 (or no packages). That is, when you pass a single package name or
630 source files (*.java) belonging to a single package as arguments into
631 the javadoc command, it will create only one frame (C) in the left-hand
632 column -- the list of classes. When you pass into javadoc two or more
633 package names, it creates a third frame (P) listing all packages, as
634 well as an overview page (Detail). This overview page has the filename
635 overview-summary.html. Thus, this file is created only if you pass in
636 two or more package names. You can bypass frames by clicking on the "No
637 Frames" link or entering at overview-summary.html.
638 If you are unfamiliar with HTML frames, you should be aware that frames
640 can have focus for printing and scrolling. To give a frame focus, click
641 on it. Then on many browsers the arrow keys and page keys will scroll
642 that frame, and the print menu command will print it.
643 ------------ ------------
645 |C| Detail | |P| Detail |
646 | | | | | |
647 | | | |-| |
648 | | | |C| |
649 | | | | | |
650 | | | | | |
651 ------------ ------------
652 javadoc *.java javadoc java.lang java.awt
653 Load one of the following two files as the starting page depending on
656 whether you want HTML frames or not:
657 o index.html (for frames)
659 o overview-summary.html (for no frames)
661 Generated File Structure
664 The generated class and interface files are organized in the same
666 directory hierarchy that Java source files and class files are orga‐
667 nized. This structure is one directory per subpackage.
668 For example, the document generated for the class java.applet.Applet
670 class would be located at java/applet/Applet.html. The file structure
671 for the java.applet package follows, given that the destination direc‐
672 tory is named apidocs. All files that contain the word "frame" appear
673 in the upper-left or lower-left frames, as noted. All other HTML files
674 appear in the right-hand frame.
675 NOTE - Directories are shown in bold. The asterisks (*) indicate the
677 files and directories that are omitted when the arguments to javadoc
678 are source filenames (*.java) rather than package names. Also when
679 arguments are source filenames, package-list is created but is
680 empty. The doc-files directory will not be created in the destina‐
681 tion unless it exists in the source tree.
682 apidocs Top directory
684 index.html Initial page that sets up HTML frames
685 * overview-summary.html Lists all packages with first sentence summaries
686 overview-tree.html Lists class hierarchy for all packages
687 deprecated-list.html Lists deprecated API for all packages
688 constant-values.html Lists values of static fields for all packages
689 serialized-form.html Lists serialized form for all packages
690 * overview-frame.html Lists all packages, used in upper-left frame
691 allclasses-frame.html Lists all classes for all packages, used in lower-left frame
692 help-doc.html Lists user help for how these pages are organized
693 index-all.html Default index created without -splitindex option
694 index-files Directory created with -splitindex option
695 index-<number>.html Index files created with -splitindex option
696 package-list Lists package names, used only for resolving external refs
697 stylesheet.css HTML style sheet for defining fonts, colors and positions
698 java Package directory
699 applet Subpackage directory
700 Applet.html Page for Applet class
701 AppletContext.html Page for AppletContext interface
702 AppletStub.html Page for AppletStub interface
703 AudioClip.html Page for AudioClip interface
704 * package-summary.html Lists classes with first sentence summaries for this package
705 * package-frame.html Lists classes in this package, used in lower left-hand frame
706 * package-tree.html Lists class hierarchy for this package
707 package-use Lists where this package is used
708 doc-files Directory holding image and example files
709 class-use Directory holding pages API is used
710 Applet.html Page for uses of Applet class
711 AppletContext.html Page for uses of AppletContext interface
712 AppletStub.html Page for uses of AppletStub interface
713 AudioClip.html Page for uses of AudioClip interface
714 src-html Source code directory
715 java Package directory
716 applet Subpackage directory
717 Applet.html Page for Applet source code
718 AppletContext.html Page for AppletContext source code
719 AppletStub.html Page for AppletStub source code
720 AudioClip.html Page for AudioClip source code
721 a name="generatedapideclarations"/> Generated API Declarations
724 The Javadoc tool generates a declaration at the start of each class,
725 interface, field, constructor, and method description for that API
726 item. For example, the declaration for the Boolean class is:
727 public final class Boolean
729 extends Object
730 implements Serializable
731 and the declaration for the Boolean.valueOfmethod is:
733 public static Boolean valueOf(String s)
735 The Javadoc tool can include the modifiers public, protected, private,
737 abstract, final, static, transient, and volatile, but not synchronized
738 or native. These last two modifiers are considered implementation
739 detail and not part of the API specification.
740 Rather than relying on the keyword synchronized, APIs should document
742 their concurrency semantics in the comment's main description, as in "a
743 single Enumeration cannot be used by multiple threads concurrently".
744 The document should not describe how to achieve these semantics. As
745 another example, while Hashtable should be thread-safe, there's no rea‐
746 son to specify that we achieve this by synchronizing all of its
747 exported methods. We should reserve the right to synchronize internally
748 at the bucket level, thus offering higher concurrency.
749
751 The original "Documentation Comment Specification" can be found under
752 related documentation.
753 Commenting the Source Code
755 You can include documentation comments ("doc comments") in the source
756 code, ahead of declarations for any class, interface, method, construc‐
757 tor, or field. You can also create doc comments for each package and
758 another one for the overview, though their syntax is slightly differ‐
759 ent. Doc comments are also known informally as "Javadoc comments" (but
760 this term violates its trademark usage). A doc comment consists of the
761 characters between the characters /** that begin the comment and the
762 characters */ that end it. Leading asterisks are allowed on each line
763 and are described further below. The text in a comment can continue
764 onto multiple lines.
765 /**
767 * This is the typical format of a simple documentation comment
768 * that spans two lines.
769 */
770 To save space you can put a comment on one line:
773 /** This comment takes up only one line. */
775 Placement of comments - Documentation comments are recognized only when
778 placed immediately before class, interface, constructor, method, or
779 field declarations -- see the class example, method example, and field
780 example. Documentation comments placed in the body of a method are
781 ignored. Only one documentation comment per declaration statement is
782 recognized by the Javadoc tool.
783 A common mistake is to put an import statement between the class com‐
785 ment and the class declaration. Avoid this, as the Javadoc tool will
786 ignore the class comment.
787 /**
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‐
799 tion - The main description begins after the starting delimiter /** and
800 continues until the tag section. The tag section starts with the first
801 block tag, which is defined by the first @ character that begins a line
802 (ignoring leading asterisks, white space, and leading separator /**).
803 It is possible to have a comment with only a tag section and no main
804 description. The main description cannot continue after the tag section
805 begins. The argument to a tag can span multiple lines. There can be any
806 number of tags -- some types of tags can be repeated while others can‐
807 not. For example, this @see starts the tag section:
808 /**
810 * This sentence would hold the main description for this doc comment.
811 * @see java.lang.Object
812 */
813 Block tags and in-line tags - A tag is a special keyword within a doc
816 comment that the Javadoc tool can process. There are two kinds of tags:
817 block tags, which appear as @tag (also known as "standalone tags"), and
818 in-line tags, which appear within curly braces, as {@tag}. To be inter‐
819 preted, a block tag must appear at the beginning of a line, ignoring
820 leading asterisks, white space, and separator (/**). This means you can
821 use the @ character elsewhere in the text and it will not be inter‐
822 preted as the start of a tag. If you want to start a line with the @
823 character and not have it be interpreted, use the HTML entity @.
824 Each block tag has associated text, which includes any text following
825 the tag up to, but not including, either the next tag, or the end of
826 the doc comment. This associated text can span multiple lines. An
827 in-line tag is allowed and interpreted anywhere that text is allowed.
828 The following example contains the block tag @deprecated and in-line
829 tag {@link}.
830 /**
832 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
833 */
834 Comments are written in HTML - The text must be written in HTML, in
837 that they should use HTML entities and can use HTML tags. You can use
838 whichever version of HTML your browser supports; we have written the
839 standard doclet to generate HTML 3.2-compliant code elsewhere (outside
840 of the documentation comments) with the inclusion of cascading style
841 sheets and frames. (We preface each generated file with "HTML 4.0"
842 because of the frame sets.)
843 For example, entities for the less-than (<) and greater-than (>) sym‐
845 bols should be written < and >. Likewise, the ampersand (&) should be
846 written &. The bold HTML tag <b> is shown in the following example.
847 Here is a doc comment:
849 /**
851 * This is a <b>doc</b> comment.
852 * @see java.lang.Object
853 */
854 Leading asterisks - When javadoc parses a doc comment, leading asterisk
857 (*) characters on each line are discarded; blanks and tabs preceding
858 the initial asterisk (*) characters are also discarded. Starting with
859 1.4, if you omit the leading asterisk on a line, the leading white
860 space is no longer removed. This enables you to paste code examples
861 directly into a doc comment inside a <PRE> tag, and its indentation
862 will be honored. Spaces are generally interpreted by browsers more uni‐
863 formly than tabs. Indentation is relative to the left margin (rather
864 than the separator /** or <PRE> tag).
865 First sentence - The first sentence of each doc comment should be a
867 summary sentence, containing a concise but complete description of the
868 declared entity. This sentence ends at the first period that is fol‐
869 lowed by a blank, tab, or line terminator, or at the first block tag.
870 The Javadoc tool copies this first sentence to the member summary at
871 the top of the HTML page.
872 Declaration with multiple fields - Java allows declaring multiple
874 fields in a single statement, but this statement can have only one doc‐
875 umentation comment, which is copied for all fields. Therefore if you
876 want individual documentation comments for each field, you must declare
877 each field in a separate statement. For example, the following documen‐
878 tation comment doesn't make sense written as a single declaration and
879 would be better handled as two declarations:
880 /**
882 * The horizontal and vertical distances of point (x,y)
883 */
884 public int x, y; // Avoid this
885 The Javadoc tool generates the following documentation from the above
888 code:
889 public int x
891 The horizontal and vertical distances of point (x,y)
894 public int y
897 The horizontal and vertical distances of point (x,y)
900 Use header tags carefully - When writing documentation comments for
903 members, it's best not to use HTML heading tags such as <H1> and <H2>,
904 because the Javadoc tool creates an entire structured document and
905 these structural tags might interfere with the formatting of the gener‐
906 ated document. However, it is fine to use these headings in class and
907 package comments to provide your own structure.
908 Automatic Copying of Method Comments
910 The Javadoc tool has the ability to copy or "inherit" method comments
911 in classes and interfaces under the following two circumstances. Con‐
912 structors, fields and nested classes do not inherit doc comments.
913 o Automatically inherit comment to fill in missing text - When a
915 main description, or @return, @param or @throws tag is missing
916 from a method comment, the Javadoc tool copies the corresponding
917 main description or tag comment from the method it overrides or
918 implements (if any), according to the algorithm below.
919 More specifically, when a @param tag for a particular parameter is
921 missing, then the comment for that parameter is copied from the
922 method further up the inheritance hierarchy. When a @throws tag for
923 a particular exception is missing, the @throws tag is copied only if
924 that exception is declared.
925 This behavior contrasts with version 1.3 and earlier, where the
927 presence of any main description or tag would prevent all comments
928 from being inherited.
929 o Explicitly inherit comment with {@inheritDoc} tag - Insert the
931 inline tag {@inheritDoc} in a method main description or @return,
932 @param or @throws tag comment -- the corresponding inherited main
933 description or tag comment is copied into that spot.
934 The source file for the inherited method need only be on the path spec‐
937 ified by -sourcepath for the doc comment to actually be available to
938 copy. Neither the class nor its package needs to be passed in on the
939 command line. This contrasts with 1.3.x and earlier releases, where the
940 class had to be a documented class
941 Inherit from classes and interfaces - Inheriting of comments occurs in
943 all three possible cases of inheritance from classes and interfaces:
944 o When a method in a class overrides a method in a superclass
946 o When a method in an interface overrides a method in a superinter‐
948 face
949 o When a method in a class implements a method in an interface
951 In the first two cases, for method overrides, the Javadoc tool gener‐
954 ates a subheading "Overrides" in the documentation for the overriding
955 method, with a link to the method it is overriding, whether or not the
956 comment is inherited.
957 In the third case, when a method in a given class implements a method
959 in an interface, the Javadoc tool generates a subheading "Specified by"
960 in the documentation for the overriding method, with a link to the
961 method it is implementing. This happens whether or not the comment is
962 inherited.
963 Algorithm for Inheriting Method Comments - If a method does not have a
965 doc comment, or has an {@inheritDoc} tag, the Javadoc tool searches for
966 an applicable comment using the following algorithm, which is designed
967 to find the most specific applicable doc comment, giving preference to
968 interfaces over superclasses:
969 1. Look in each directly implemented (or extended) interface in the
971 order they appear following the word implements (or extends) in
972 the method declaration. Use the first doc comment found for this
973 method.
974 2. If step 1 failed to find a doc comment, recursively apply this
976 entire algorithm to each directly implemented (or extended)
977 interface, in the same order they were examined in step 1.
978 3. If step 2 failed to find a doc comment and this is a class other
980 than Object (not an interface):
981 a. If the superclass has a doc comment for this method, use it.
983 b. If step 3a failed to find a doc comment, recursively apply
985 this entire algorithm to the superclass.
986
989 The Javadoc tool parses special tags when they are embedded within a
990 Java doc comment. These doc tags enable you to autogenerate a complete,
991 well-formatted API from your source code. The tags start with an "at"
992 sign (@) and are case-sensitive -- they must be typed with the upper‐
993 case and lowercase letters as shown. A tag must start at the beginning
994 of a line (after any leading spaces and an optional asterisk) or it is
995 treated as normal text. By convention, tags with the same name are
996 grouped together. For example, put all @see tags together.
997 Tags come in two types:
999 o Block tags - Can be placed only in the tag section that follows
1001 the main description. Block tags are of the form: @tag.
1002 o Inline tags - Can be placed anywhere in the main description or in
1004 the comments for block tags. Inline tags are denoted by curly
1005 braces: {@tag}.
1006 For information about tags we might introduce in future releases, see
1009 Proposed Tags @
1010 http://java.sun.com/j2se/javadoc/proposed-tags.html.
1011 The current tags are:
1013 For custom tags, see the -tag option.
1015 @author name-text
1017 Adds an "Author" entry with the specified name-text to the gener‐
1018 ated docs when the -author option is used. A doc comment may con‐
1019 tain multiple @author tags. You can specify one name per @author
1020 tag or multiple names per tag. In the former case, the Javadoc
1021 tool inserts a comma (,) and space between names. In the latter
1022 case, the entire text is simply copied to the generated document
1023 without being parsed. Therefore, you can use multiple names per
1024 line if you want a localized name separator other than comma.
1025 For more details, see Where Tags Can Be Used and writing @author
1027 tags @
1028 http://java.sun.com/j2se/javadoc/writingdoccom‐
1029 ments/index.html#@author.
1030 @deprecated deprecated-text
1032 Note: Starting with JDK 5.0, you can deprecate a program element
1035 using the @Deprecated annotation.
1036 Adds a comment indicating that this API should no longer be used
1038 (even though it may continue to work). The Javadoc tool moves the
1039 deprecated-text ahead of the main description, placing it in italics
1040 and preceding it with a bold warning: "Deprecated". This tag is
1041 valid in all doc comments: overview, package, class, interface, con‐
1042 structor, method and field.
1043 The first sentence of deprecated-text should at least tell the user
1045 when the API was deprecated and what to use as a replacement. The
1046 Javadoc tool copies just the first sentence to the summary section
1047 and index. Subsequent sentences can also explain why it has been
1048 deprecated. You should include a {@link} tag (for Javadoc 1.2 or
1049 later) that points to the replacement API:
1050 For more details, see writing @deprecated tags @
1052 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@dep‐
1053 recated.
1054 o For Javadoc 1.2 and later, use a {@link} tag. This creates the
1056 link in-line, where you want it. For example:
1057 /**
1058 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
1059 */
1060 o For Javadoc 1.1, the standard format is to create a @see tag
1062 (which cannot be in-line) for each @deprecated tag.
1063 For more about deprecation, see The @deprecated tag.
1065 {@code text}
1067 Equivalent to <code>{@literal}</code>.
1068 Displays text in code font without interpreting the text as HTML
1070 markup or nested javadoc tags. This enables you to use regular angle
1071 brackets (< and >) instead of the HTML entities (< and >) in doc
1072 comments, such as in parameter types (<Object>), inequalities (3 <
1073 4), or arrows (<-). For example, the doc comment text:
1074 {@code A<B>C}
1075 displays in the generated HTML page unchanged, as:
1076 A<B>C
1077 The noteworthy point is that the <B> is not interpreted as bold and
1078 is in code font.
1079 If you want the same functionality without the code font, use {@lit‐
1081 eral}.
1082 {@docRoot}
1084 Represents the relative path to the generated document's (desti‐
1085 nation) root directory from any generated page. It is useful when
1086 you want to include a file, such as a copyright page or company
1087 logo, that you want to reference from all generated pages. Link‐
1088 ing to the copyright page from the bottom of each page is common.
1089 This {@docRoot} tag can be used both on the command line and in a
1091 doc comment: This tag is valid in all doc comments: overview, pack‐
1092 age, class, interface, constructor, method and field, including the
1093 text portion of any tag (such as @return, @param and @deprecated).
1094 1. On the command line, where the header/footer/bottom are
1096 defined:
1097 javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
1098 NOTE - When using {@docRoot} this way in a make file, some
1099 makefile programs require special escaping for the brace {}
1100 characters. For example, the Inprise MAKE version 5.2 running
1101 on Windows requires double braces: {{@docRoot}}. It also
1102 requires double (rather than single) quotes to enclose argu‐
1103 ments to options such as -bottom (with the quotes around the
1104 href argument omitted).
1105 2. In a doc comment:
1107 /**
1108 * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
1109 */
1110 The reason this tag is needed is because the generated docs are in
1111 hierarchical directories, as deep as the number of subpackages. This
1112 expression:
1113 <a href="{@docRoot}/copyright.html">
1114 would resolve to:
1115 <a href="../../copyright.html"> for java/lang/Object.java
1116 and
1117 <a href="../../../copyright.html"> for java/lang/ref/Reference.java
1118 @exception class-name description
1120 The @exception tag is a synonym for @throws.
1121 {@inheritDoc}
1123 Inherits (copies) documentation from the "nearest" inheritable
1124 class or implementable interface into the current doc comment at
1125 this tag's location. This allows you to write more general com‐
1126 ments higher up the inheritance tree, and to write around the
1127 copied text.
1128 This tag is valid only in these places in a doc comment:
1130 o In the main description block of a method. In this case, the
1132 main description is copied from a class or interface up the
1133 hierarchy.
1134 o In the text arguments of the @return, @param and @throws tags
1136 of a method. In this case, the tag text is copied from the cor‐
1137 responding tag up the hierarchy.
1138 See Automatic Copying of Method Comments for a more precise descrip‐
1140 tion of how comments are found in the inheritance hierarchy. Note
1141 that if this tag is missing, the comment is or is not automatically
1142 inherited according to rules described in that section.
1143 {@link package.class#member label}
1145 Inserts an in-line link with visible text label that points to
1146 the documentation for the specified package, class or member name
1147 of a referenced class. This tag is valid in all doc comments:
1148 overview, package, class, interface, constructor, method and
1149 field, including the text portion of any tag (such as @return,
1150 @param and @deprecated).
1151 This tag is very simliar to @see -- both require the same references
1153 and accept exactly the same syntax for package.class#member and
1154 label. The main difference is that {@link} generates an in-line link
1155 rather than placing the link in the "See Also" section. Also, the
1156 {@link} tag begins and ends with curly braces to separate it from
1157 the rest of the in-line text. If you need to use "}" inside the
1158 label, use the HTML entity notation }
1159 There is no limit to the number of {@link} tags allowed in a sen‐
1161 tence. You can use this tag in the main description part of any doc‐
1162 umentation comment or in the text portion of any tag (such as @dep‐
1163 recated, @return or @param).
1164 For example, here is a comment that refers to the getComponen‐
1166 tAt(int, int) method:
1167 Use the {@link #getComponentAt(int, int) getComponentAt} method.
1168 From this, the standard doclet would generate the following HTML
1169 (assuming it refers to another class in the same package):
1170 Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
1171 Which appears on the web page as:
1172 Use the getComponentAt method.
1173 You can extend {@link} to link to classes not being documented by
1174 using the -link option.
1175 For more details, see writing {@link} tags @
1177 http://java.sun.com/j2se/javadoc/writingdoccom‐
1178 ments/index.html#{@link}.
1179 {@linkplain package.class#member label}
1181 Identical to {@link}, except the link's label is displayed in
1182 plain text than code font. Useful when the label is plain text.
1183 Example:
1184 Refer to {@linkplain add() the overridden method}.
1185 This would display as:
1186 Refer to the overridden method.
1188 {@literal text}
1190 Displays text without interpreting the text as HTML markup or
1191 nested javadoc tags. This enables you to use regular angle brack‐
1192 ets (< and >) instead of the HTML entities (< and >) in doc com‐
1193 ments, such as in parameter types (<Object>), inequalities (3 <
1194 4), or arrows (<-). For example, the doc comment text:
1195 {@literal A<B>C}
1196 displays unchanged in the generated HTML page in your browser,
1197 as:
1198 A<B>C The noteworthy point is that the <B> is not interpreted
1200 as bold (and it is not in code font).
1201 If you want the same functionality but with the text in code font,
1203 use {@code}.
1204 @param parameter-name description
1206 Adds a parameter with the specified parameter-name followed by
1207 the specified description to the "Parameters" section. When writ‐
1208 ing the doc comment, you may continue the description onto multi‐
1209 ple lines. This tag is valid only in a doc comment for a method,
1210 constructor or class.
1211 The parameter-name can be the name of a parameter in a method or
1213 constructor, or the name of a type parameter of a class, method or
1214 constructor. Use angle brackets around this parameter name to spec‐
1215 ify the use of a type parameter.
1216 Example of a type parameter of a class:
1218 /**
1219 * @param <E> Type of element stored in a list
1220 */
1221 public interface List<E> extends Collection<E> {
1222 }
1223 Example of a type parameter of a method:
1225 /**
1226 * @param string the string to be converted
1227 * @param type the type to convert the string to
1228 * @param <T> the type of the element
1229 * @param <V> the value of the element
1230 */
1231 <T, V extends T> V convert(String string, Class<T> type) {
1232 }
1233 For more details, see writing @param tags @
1234 http://java.sun.com/j2se/javadoc/writingdoccom‐
1235 ments/index.html#@param.
1236 @return description
1238 Adds a "Returns" section with the description text. This text
1239 should describe the return type and permissible range of values.
1240 This tag is valid only in a doc comment for a method.
1241 For more details, see writing @return tags @
1243 http://java.sun.com/j2se/javadoc/writingdoccom‐
1244 ments/index.html#@return.
1245 @see reference
1247 Adds a "See Also" heading with a link or text entry that points
1248 to reference. A doc comment may contain any number of @see tags,
1249 which are all grouped under the same heading. The @see tag has
1250 three variations; the third form below is the most common. This
1251 tag is valid in any doc comment: overview, package, class, inter‐
1252 face, constructor, method or field. For inserting an in-line link
1253 within a sentence to a package, class or member, see {@link}.
1254 @see "string"
1256 Adds a text entry for string. No link is generated. The string
1257 is a book or other reference to information not available by
1258 URL. The Javadoc tool distinguishes this from the previous
1259 cases by looking for a double-quote (") as the first charac‐
1260 ter. For example:
1261 @see "The Java Programming Language"
1262 This generates text such as:
1263 See Also:
1265 "The Java Programming Language"
1266 @see <a href="URL#value">label</a>
1269 Adds a link as defined by URL#value. The URL#value is a rela‐
1270 tive or absolute URL. The Javadoc tool distinguishes this from
1271 other cases by looking for a less-than symbol (<) as the first
1272 character. For example:
1273 @see <a href="spec.html#section">Java Spec</a>
1274 This generates a link such as:
1275 See Also:
1277 Java Spec
1278 @see package.class#member label
1281 Adds a link, with visible text label, that points to the docu‐
1282 mentation for the specified name in the Java Language that is
1283 referenced. The label is optional; if omitted, the name
1284 appears instead as the visible text, suitably shortened -- see
1285 How a name is displayed. Use -noqualifier to globally remove
1286 the package name from this visible text. Use the label when
1287 you want the visible text to be different from the auto-gener‐
1288 ated visible text.
1289 Only in version 1.2, just the name but not the label would auto‐
1291 matically appear in <code> HTML tags, Starting with 1.2.2, the
1292 <code> is always included around the visible text, whether or not
1293 a label is used.
1294 o package.class#member is any valid program element name that
1296 is referenced -- a package, class, interface, constructor,
1297 method or field name -- except that the character ahead of
1298 the member name should be a hash character (#). The class
1299 represents any top-level or nested class or interface. The
1300 member represents any constructor, method or field (not a
1301 nested class or interface). If this name is in the docu‐
1302 mented classes, the Javadoc tool will automatically create a
1303 link to it. To create links to external referenced classes,
1304 use the -link option. Use either of the other two @see forms
1305 for referring to documentation of a name that does not
1306 belong to a referenced class. This argument is described at
1307 greater length below under Specifying a Name.
1308 o label is optional text that is visible as the link's label.
1310 The label can contain whitespace. If label is omitted, then
1311 package.class.member will appear, suitably shortened rela‐
1312 tive to the current class and package -- see How a name is
1313 displayed.
1314 o A space is the delimiter between package.class#member and
1316 label. A space inside parentheses does not indicate the
1317 start of a label, so spaces may be used between parameters
1318 in a method.
1319 Example - In this example, an @see tag (in the Character class)
1321 refers to the equals method in the String class. The tag includes
1322 both arguments: the name "String#equals(Object)" and the label
1323 "equals".
1324 /**
1325 * @see String#equals(Object) equals
1326 */
1327 The standard doclet produces HTML something like this:
1328 <dl>
1331 <dt><b>See Also:</b>
1332 <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
1333 </dl>
1334 Which looks something like this in a browser, where the label is
1335 the visible link text:
1336 See Also:
1339 equals
1340 Specifying a name - This package.class#member name can be either
1343 fully-qualified, such as java.lang.String#toUpperCase() or not,
1344 such as String#toUpperCase() or #toUpperCase(). If less than
1345 fully-qualified, the Javadoc tool uses the normal Java compiler
1346 search order to find it, further described below in Search order
1347 for @see. The name can contain whitespace within parentheses,
1348 such as between method arguments.
1349 Of course the advantage of providing shorter, "partially-quali‐
1351 fied" names is that they are shorter to type and there is less
1352 clutter in the source code. The following table shows the differ‐
1353 ent forms of the name, where Class can be a class or interface,
1354 Type can be a class, interface, array, or primitive, and method
1355 can be a method or constructor.
1356 The following notes apply to the above table:
1358 o The first set of forms (with no class or package) will cause
1360 the Javadoc tool to search only through the current class's
1361 hierarchy. It will find a member of the current class or
1362 interface, one of its superclasses or superinterfaces, or
1363 one of its enclosing classes or interfaces (search steps
1364 1-3). It will not search the rest of the current package or
1365 other packages (search steps 4-5).
1366 o If any method or constructor is entered as a name with no
1368 parentheses, such as getValue, and if there is no field with
1369 the same name, the Javadoc tool will correctly create a link
1370 to it, but will print a warning message reminding you to add
1371 the parentheses and arguments. If this method is overloaded,
1372 the Javadoc tool will link to the first method its search
1373 encounters, which is unspecified.
1374 o Nested classes must be specified as outer.inner, not simply
1376 inner, for all forms.
1377 o As stated, the hash character (#), rather than a dot (.)
1379 separates a member from its class. This enables the Javadoc
1380 tool to resolve ambiguities, since the dot also separates
1381 classes, nested classes, packages, and subpackages. However,
1382 the Javadoc tool is generally lenient and will properly
1383 parse a dot if you know there is no ambiguity, though it
1384 will print a warning.
1385 Search order for @see - the Javadoc tool will process a @see tag
1387 that appears in a source file (.java), package file (package.html
1388 or package-info.java) or overview file (overview.html). In the
1389 latter two files, you must fully-qualify the name you supply with
1390 @see. In a source file, you can specify a name that is
1391 fully-qualified or partially-qualified.
1392 When the Javadoc tool encounters a @see tag in a .java file that
1394 is not fully qualified, it searches for the specified name in the
1395 same order as the Java compiler would (except the Javadoc tool
1396 will not detect certain namespace ambiguities, since it assumes
1397 the source code is free of these errors). This search order is
1398 formally defined in Chapter 6, "Names" of the Java Language Spec‐
1399 ification, Second Edition. The Javadoc tool searches for that
1400 name through all related and imported classes and packages. In
1401 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://java.sun.com/j2se/javadoc/writingdoccom‐
1463 ments/index.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 Section 1.6 of the Java Object Serialization Specification. Also see
1501 the Serialization FAQ @
1502 http://java.sun.com/products/jdk/serializa‐
1503 tion/faq/#javadoc_warn_missing, which covers common questions, such
1504 as "Why do I see javadoc warnings stating that I am missing @serial
1505 tags for private fields if I am not running javadoc with the -pri‐
1506 vate switch?". Also see Sun's criteria @
1507 http://java.sun.com/j2se/javadoc/writingapispecs/serialized-crite‐
1508 ria.html for including classes in the serialized form specification.
1509 @serialField field-name field-type field-description
1511 Documents an ObjectStreamField component of a Serializable
1512 class's serialPersistentFields member. One @serialField tag
1513 should be used for each ObjectStreamField component.
1514 @serialData data-description
1516 The data-description documents the types and order of data in the
1517 serialized form. Specifically, this data includes the optional
1518 data written by the writeObject method and all data (including
1519 base classes) written by the Externalizable.writeExternal method.
1520 The @serialData tag can be used in the doc comment for the writeOb‐
1522 ject, readObject, writeExternal, readExternal, writeReplace, and
1523 readResolve methods.
1524 @since since-text
1526 Adds a "Since" heading with the specified since-text to the gen‐
1527 erated documentation. The text has no special internal structure.
1528 This tag is valid in any doc comment: overview, package, class,
1529 interface, constructor, method or field. This tag means that this
1530 change or feature has existed since the software release speci‐
1531 fied by the since-text. For example:
1532 @since 1.5
1533 For source code in the Java platform, this tag indicates the ver‐
1534 sion of the Java platform API specification (not necessarily when
1535 it was added to the reference implementation). Multiple @since
1536 tags are allowed and are treated like multiple @author tags. You
1537 could use multiple tags if the prgram element is used by more
1538 than one API.
1539 @throws class-name description
1541 The @throws and @exception tags are synonyms. Adds a "Throws"
1542 subheading to the generated documentation, with the class-name
1543 and description text. The class-name is the name of the exception
1544 that may be thrown by the method. This tag is valid only in the
1545 doc comment for a method or constructor. If this class is not
1546 fully-specified, the Javadoc tool uses the search order to look
1547 up this class. Multiple @throws tags can be used in a given doc
1548 comment for the same or different exceptions.
1549 To ensure that all checked exceptions are documented, if a @throws
1551 tag does not exist for an exception in the throws clause, the
1552 Javadoc tool automatically adds that exception to the HTML output
1553 (with no description) as if it were documented with @throws tag.
1554 The @throws documentation is copied from an overridden method to a
1556 subclass only when the exception is explicitly declared in the over‐
1557 ridden method. The same is true for copying from an interface method
1558 to an implementing method. You can use {@inheritDoc} to force
1559 @throws to inherit documentation.
1560 For more details, see writing @throws tags @
1562 http://java.sun.com/j2se/javadoc/writingdoccom‐
1563 ments/index.html#@exception.
1564 {@value package.class#field}
1566 When {@value} is used (without any argument) in the doc comment
1567 of a static field, it displays the value of that constant:
1568 /**
1569 * The value of this constant is {@value}.
1570 */
1571 public static final String SCRIPT_START = "<script>"
1572 When used with argument package.class#field in any doc comment,
1573 it displays the value of the specified constant:
1574 /**
1575 * Evaluates the script starting with {@value #SCRIPT_START}.
1576 */
1577 public String evalScript(String script) {
1578 }
1579 The argument package.class#field takes a form identical to that
1580 of the @see argument, except that the member must be a static
1581 field.
1582 These values of these constants are also displayed on the Constant
1584 Field Values page.
1585 @version version-text
1587 Adds a "Version" subheading with the specified version-text to
1588 the generated docs when the -version option is used. This tag is
1589 intended to hold the current version number of the software that
1590 this code is part of (as opposed to @since, which holds the ver‐
1591 sion number where this code was introduced). The version-text has
1592 no special internal structure. To see where the version tag can
1593 be used, see Where Tags Can Be Used.
1594 A doc comment may contain multiple @version tags. If it makes sense,
1596 you can specify one version number per @version tag or multiple ver‐
1597 sion numbers per tag. In the former case, the Javadoc tool inserts a
1598 comma (,) and space between names. In the latter case, the entire
1599 text is simply copied to the generated document without being
1600 parsed. Therefore, you can use multiple names per line if you want a
1601 localized name separator other than comma.
1602 For more details, see writing @version tags @
1604 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@ver‐
1605 sion.
1606 Where Tags Can Be Used
1608 The following sections describe where the tags can be used. Note that
1609 these tags can be used in all doc comments: @see, @since, @deprecated,
1610 {@link}, {@linkplain}, and {@docroot}.
1611 Overview Documentation Tags
1613 Overview tags are tags that can appear in the documentation comment for
1614 the overview page (which resides in the source file typically named
1615 overview.html). Like in any other documentation comments, these tags
1616 must appear after the main description.
1617 NOTE - The {@link} tag has a bug in overview documents in version 1.2
1619 -- the text appears properly but has no link. The {@docRoot} tag does
1620 not currently work in overview documents.
1621 Package Documentation Tags
1623 Package tags are tags that can appear in the documentation comment for
1624 a package (which resides in the source file named package.html or pack‐
1625 age-info.java). The @serial tag can only be used here with the include
1626 or exclude argument.
1627 Class and Interface Documentation Tags
1629 The following are tags that can appear in the documentation comment for
1630 a class or interface. The @serial tag can only be used here with the
1631 include or exclude argument.
1632 An example of a class comment:
1634 /**
1636 * A class representing a window on the screen.
1637 * For example:
1638 * <pre>
1639 * Window win = new Window(parent);
1640 * win.show();
1641 * </pre>
1642 *
1643 * @author Sami Shaio
1644 * @version 1.13, 06/08/06
1645 * @see java.awt.BaseWindow
1646 * @see java.awt.Button
1647 */
1648 class Window extends BaseWindow {
1649 ...
1650 }
1651 Field Documentation Tags
1654 The following are the tags that can appear in the documentation comment
1655 for a field.
1656 An example of a field comment:
1658 /**
1660 * The X-coordinate of the component.
1661 *
1662 * @see #getLocation()
1663 */
1664 int x = 1263732;
1665 Constructor and Method Documentation Tags
1668 The following are the tags that can appear in the documentation comment
1669 for a constructor or method, except for @return, which cannot appear in
1670 a constructor, and {@inheritDoc}, which has certain restrictions. The
1671 @serialData tag can only be used in the doc comment for certain serial‐
1672 ization methods.
1673 An example of a method doc comment:
1675 /**
1677 * Returns the character at the specified index. An index
1678 * ranges from <code>0</code> to <code>length() - 1</code>.
1679 *
1680 * @param index the index of the desired character.
1681 * @return the desired character.
1682 * @exception StringIndexOutOfRangeException
1683 * if the index is not in the range <code>0</code>
1684 * to <code>length()-1</code>.
1685 * @see java.lang.Character#charValue()
1686 */
1687 public char charAt(int index) {
1688 ...
1689 }
1690
1693 The javadoc tool uses doclets to determine its output. The Javadoc tool
1694 uses the default standard doclet unless a custom doclet is specified
1695 with the -doclet option. The Javadoc tool provides a set of com‐
1696 mand-line options that can be used with any doclet -- these options are
1697 described below under the sub-heading Javadoc Options. The standard
1698 doclet provides an additional set of command-line options that are
1699 described below under the sub-heading Options Provided by the Standard
1700 Doclet. All option names are case-insensitive, though their arguments
1701 can be case-sensitive.
1702 The options are:
1704 Options shown in italic are the Javadoc core options, which are pro‐
1706 vided by the front end of the Javadoc tool and are available to all
1707 doclets. The standard doclet itself provides the non-italic options.
1708 Javadoc Options
1710 -overview path/filename
1711 Specifies that javadoc should retrieve the text for the overview
1712 documentation from the "source" file specified by path/filename
1713 and place it on the Overview page (overview-summary.html). The
1714 path/filename is relative to the -sourcepath.
1715 While you can use any name you want for filename and place it any‐
1717 where you want for path, a typical thing to do is to name it over‐
1718 view.html and place it in the source tree at the directory that con‐
1719 tains the topmost package directories. In this location, no path is
1720 needed when documenting packages, since -sourcepath will point to
1721 this file. For example, if the source tree for the java.lang package
1722 is /src/classes/java/lang/, then you could place the overview file
1723 at /src/classes/overview.html. See Real World Example.
1724 For information about the file specified by path/filename, see over‐
1726 view comment file.
1727 Note that the overview page is created only if you pass into javadoc
1729 two or more package names. For further explanation, see HTML
1730 Frames.)
1731 The title on the overview page is set by -doctitle.
1733 -public
1735 Shows only public classes and members.
1736 -protected
1738 Shows only protected and public classes and members. This is the
1739 default.
1740 -package
1742 Shows only package, protected, and public classes and members.
1743 -private
1745 Shows all classes and members.
1746 -help
1748 Displays the online help, which lists these javadoc and doclet
1749 command line options.
1750 -doclet class
1752 Specifies the class file that starts the doclet used in generat‐
1753 ing the documentation. Use the fully-qualified name. This doclet
1754 defines the content and formats the output. If the -doclet option
1755 is not used, javadoc uses the standard doclet for generating the
1756 default HTML format. This class must contain the start(Root)
1757 method. The path to this starting class is defined by the
1758 -docletpath option.
1759 For example, to call the MIF doclet, use:
1761 -doclet com.sun.tools.doclets.mif.MIFDoclet
1762 For full, working examples of running a particular doclet, see Run‐
1764 ning the MIF Doclet @
1765 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#run‐
1766 ningmifdoclet.
1767 -docletpath classpathlist
1769 Specifies the path to the doclet starting class file (specified
1770 with the -doclet option) and any jar files it depends on. If the
1771 starting class file is in a jar file, then this specifies the
1772 path to that jar file, as shown in the example below. You can
1773 specify an absolute path or a path relative to the current direc‐
1774 tory. If classpathlist contains multiple paths or jar files, they
1775 should be separated with a colon (:) on Solaris and a semi-colon
1776 (;) on Windows. This option is not necessary if the doclet start‐
1777 ing class is already in the search path.
1778 Example of path to jar file that contains the starting doclet class
1780 file. Notice the jar filename is included.
1781 -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
1782 Example of path to starting doclet class file. Notice the class
1783 filename is omitted.
1784 -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
1785 For full, working examples of running a particular doclet, see Run‐
1786 ning the MIF Doclet @
1787 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#run‐
1788 ningmifdoclet.
1789 -1.1
1791 This feature has been removed from Javadoc 1.4. There is no
1792 replacement for it. This option created documentation with the
1793 appearance and functionality of documentation generated by
1794 Javadoc 1.1 (it never supported nested classes). If you need this
1795 option, use Javadoc 1.2 or 1.3 instead.
1796 -source release
1798 Specifies the version of source code accepted. The following val‐
1799 ues for release are allowed:
1800 Use the value of release corresponding to that used when compiling
1802 the code with javac.
1803 -sourcepath sourcepathlist
1805 Specifies the search paths for finding source files (.java) when
1806 passing package names or -subpackages into the javadoc command.
1807 The sourcepathlist can contain multiple paths by separating them
1808 with a colon (:). The Javadoc tool will search in all subdirecto‐
1809 ries of the specified paths. Note that this option is not only
1810 used to locate the source files being documented, but also to
1811 find source files that are not being documented but whose com‐
1812 ments are inherited by the source files being documented.
1813 Note that you can use the -sourcepath option only when passing pack‐
1815 age names into the javadoc command -- it will not locate .java files
1816 passed into the javadoc command. (To locate .java files, cd to that
1817 directory or include the path ahead of each file, as shown at Docu‐
1818 menting One or More Classes.) If -sourcepath is omitted, javadoc
1819 uses the class path to find the source files (see -classpath).
1820 Therefore, the default -sourcepath is the value of class path. If
1821 -classpath is omitted and you are passing package names into
1822 javadoc, it looks in the current directory (and subdirectories) for
1823 the source files.
1824 Set sourcepathlist to the root directory of the source tree for the
1826 package you are documenting. For example, suppose you want to docu‐
1827 ment a package called com.mypackage whose source files are located
1828 at:
1829 /home/user/src/com/mypackage/*.java
1830 In this case you would specify the sourcepath to /home/user/src, the
1831 directory that contains com/mypackage, and then supply the package
1832 name com.mypackage:
1833 % javadoc -sourcepath /home/user/src/ com.mypackage
1834 This is easy to remember by noticing that if you concatenate the
1835 value of sourcepath and the package name together and change the dot
1836 to a slash "/", you end up with the full path to the package:
1837 /home/user/src/com/mypackage.
1838 To point to two source paths:
1840 % javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage
1841 -classpath classpathlist
1843 Specifies the paths where javadoc will look for referenced
1844 classes (.class files) -- these are the documented classes plus
1845 any classes referenced by those classes. The classpathlist can
1846 contain multiple paths by separating them with a colon (:). The
1847 Javadoc tool will search in all subdirectories of the specified
1848 paths. Follow the instructions in class path documentation for
1849 specifying classpathlist.
1850 If -sourcepath is omitted, the Javadoc tool uses -classpath to find
1852 the source files as well as class files (for backward compatibil‐
1853 ity). Therefore, if you want to search for source and class files in
1854 separate paths, use both -sourcepath and -classpath.
1855 For example, if you want to document com.mypackage, whose source
1857 files reside in the directory /home/user/src/com/mypackage, and if
1858 this package relies on a library in /home/user/lib, you would spec‐
1859 ify:
1860 % javadoc -classpath /home/user/lib -sourcepath /home/user/src com.mypackage
1861 As with other tools, if you do not specify -classpath, the Javadoc
1862 tool uses the CLASSPATH environment variable, if it is set. If both
1863 are not set, the Javadoc tool searches for classes from the current
1864 directory.
1865 For an in-depth description of how the Javadoc tool uses -classpath
1867 to find user classes as it relates to extension classes and boot‐
1868 strap classes, see How Classes Are Found.
1869 As a special convenience, a class path element containing a basename
1871 of * is considered equivalent to specifying a list of all the files
1872 in the directory with the extension .jar or .JAR (a java program
1873 cannot tell the difference between the two invocations).
1874 For example, if directory foo contains a.jar and b.JAR, then the
1875 class path element foo/* is expanded to a A.jar:b.JAR, except that
1876 the order of jar files is unspecified. All jar files in the speci‐
1877 fied directory, even hidden ones, are included in the list. A class‐
1878 path entry consisting simply of * expands to a list of all the jar
1879 files in the current directory. The CLASSPATH environment variable,
1880 where defined, will be similarly expanded. Any classpath wildcard
1881 expansion occurs before the Java virtual machine is started -- no
1882 Java program will ever see unexpanded wildcards except by querying
1883 the environment. For example; by invoking System.getenv("CLASS‐
1884 PATH").
1885 -subpackages package1:package2:...
1887 Generates documentation from source files in the specified pack‐
1888 ages and recursively in their subpackages. This option is useful
1889 when adding new subpackages to the source code, as they are auto‐
1890 matically included. Each package argument is any top-level sub‐
1891 package (such as java) or fully qualified package (such as
1892 javax.swing) that does not need to contain source files. Argu‐
1893 ments are separated by colons (on all operating systmes). Wild‐
1894 cards are not needed or allowed. Use -sourcepath to specify where
1895 to find the packages. This option is smart about not processing
1896 source files that are in the source tree but do not belong to the
1897 packages, as described at processing of source files.
1898 For example:
1900 % javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
1901 This command generates documentation for packages named "java" and
1902 "javax.swing" and all their subpackages.
1903 You can use -subpackages in conjunction with -exclude to exclude
1905 specific packages.
1906 -exclude packagename1:packagename2:...
1908 Unconditionally excludes the specified packages and their sub‐
1909 packages from the list formed by -subpackages. It excludes those
1910 packages even if they would otherwise be included by some previ‐
1911 ous or later -subpackages option. For example:
1912 % javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
1913 would include java.io, java.util, and java.math (among others),
1914 but would exclude packages rooted at java.net and java.lang.
1915 Notice this excludes java.lang.ref, a subpackage of java.lang).
1916 -bootclasspath classpathlist
1918 Specifies the paths where the boot classes reside. These are nom‐
1919 inally the Java platform classes. The bootclasspath is part of
1920 the search path the Javadoc tool will use to look up source and
1921 class files. See How Classes Are Found. for more details. Sepa‐
1922 rate directories in classpathlist with colons (:).
1923 -extdirs dirlist
1925 Specifies the directories where extension classes reside. These
1926 are any classes that use the Java Extension mechanism. The
1927 extdirs is part of the search path the Javadoc tool will use to
1928 look up source and class files. See -classpath (above) for more
1929 details. Separate directories in dirlist with colons (:).
1930 -verbose
1932 Provides more detailed messages while javadoc is running. Without
1933 the verbose option, messages appear for loading the source files,
1934 generating the documentation (one message per source file), and
1935 sorting. The verbose option causes the printing of additional
1936 messages specifying the number of milliseconds to parse each java
1937 source file.
1938 -quiet
1940 Shuts off non-error and non-warning messages, leaving only the
1941 warnings and errors appear, making them easier to view. Also sup‐
1942 presses the version string.
1943 -breakiterator
1945 Uses the internationalized sentence boundary of
1946 java.text.BreakIterator to determine the end of the first sen‐
1947 tence for English (all other locales already use BreakIterator),
1948 rather than an English language, locale-specific algorithm. By
1949 first sentence, we mean the first sentence in the main descrip‐
1950 tion of a package, class or member. This sentence is copied to
1951 the package, class or member summary, and to the alphabetic
1952 index.
1953 From JDK 1.2 forward, the BreakIterator class is already used to
1955 determine the end of sentence for all languages but English. There‐
1956 fore, the -breakiterator option has no effect except for English
1957 from 1.2 forward. English has its own default algorithm:
1958 o English default sentence-break algorithm - Stops at a period
1960 followed by a space or a HTML block tag, such as <P>.
1961 o Breakiterator sentence-break algorithm - In general, stops at a
1963 period, question mark or exclamation mark followed by a space
1964 if the next word starts with a capital letter. This is meant to
1965 handle most abbreviations (such as "The serial no. is valid",
1966 but won't handle "Mr. Smith"). Doesn't stop at HTML tags or
1967 sentences that begin with numbers or symbols. Stops at the last
1968 period in "../filename", even if embedded in an HTML tag.
1969 NOTE: We have removed from 1.5.0 the breakiterator warning mes‐
1972 sages that were in 1.4.x and have left the default sentence-break
1973 algorithm unchanged. That is, the -breakiterator option is not
1974 the default in 1.5.0, nor do we expect it to become the default.
1975 This is a reversal from our former intention that the default
1976 would change in the "next major release" (1.5.0). This means if
1977 you have not modified your source code to eliminate the breakit‐
1978 erator warnings in 1.4.x, then you don't have to do anything, and
1979 the warnings go away starting with 1.5.0. The reason for this
1980 reversal is because any benefit to having breakiterator become
1981 the default would be outweighed by the incompatible source change
1982 it would require. We regret any extra work and confusion this has
1983 caused.
1984 -locale language_country_variant
1986 Important - The -locale option must be placed ahead (to the left)
1988 of any options provided by the standard doclet or any other
1989 doclet. Otherwise, the navigation bars will appear in English.
1990 This is the only command-line option that is order-dependent.
1991 Specifies the locale that javadoc uses when generating documenta‐
1993 tion. The argument is the name of the locale, as described in
1994 java.util.Locale documentation, such as en_US (English, United
1995 States) or en_US_WIN (Windows variant).
1996 Specifying a locale causes javadoc to choose the resource files of
1998 that locale for messages (strings in the navigation bar, headings
1999 for lists and tables, help file contents, comments in
2000 stylesheet.css, and so forth). It also specifies the sorting order
2001 for lists sorted alphabetically, and the sentence separator to
2002 determine the end of the first sentence. It does not determine the
2003 locale of the doc comment text specified in the source files of the
2004 documented classes.
2005 -encoding name
2007 Specifies the encoding name of the source files, such as
2008 EUCJIS/SJIS. If this option is not specified, the platform
2009 default converter is used.
2010 Also see -docencoding and -charset.
2012 -Jflag
2014 Passes flag directly to the runtime system java that runs
2015 javadoc. Notice there must be no space between the J and the
2016 flag. For example, if you need to ensure that the system sets
2017 aside 32 megabytes of memory in which to process the generated
2018 documentation, then you would call the -Xmx option of java as
2019 follows (-Xms is optional, as it only sets the size of initial
2020 memory, which is useful if you know the minimum amount of memory
2021 required):
2022 % javadoc -J-Xmx32m -J-Xms32m com.mypackage
2023 To tell what version of javadoc you are using, call the "-ver‐
2024 sion" option of java:
2025 % javadoc -J-version
2026 java version "1.2"
2027 Classic VM (build JDK-1.2-V, green threads, sunwjit)
2028 (The version number of the standard doclet appears in its output
2029 stream.)
2030 Options Provided by the Standard Doclet
2032 -d directory
2033 Specifies the destination directory where javadoc saves the gen‐
2034 erated HTML files. (The "d" means "destination.") Omitting this
2035 option causes the files to be saved to the current directory. The
2036 value directory can be absolute, or relative to the current work‐
2037 ing directory. As of 1.4, the destination directory is automati‐
2038 cally created when javadoc is run.
2039 For example, the following generates the documentation for the pack‐
2041 age com.mypackage and saves the results in the /home/user/doc/
2042 directory:
2043 % javadoc -d /home/user/doc com.mypackage
2044 -use
2046 Includes one "Use" page for each documented class and package.
2047 The page describes what packages, classes, methods, constructors
2048 and fields use any API of the given class or package. Given class
2049 C, things that use class C would include subclasses of C, fields
2050 declared as C, methods that return C, and methods and construc‐
2051 tors with parameters of type C.
2052 For example, let's look at what might appear on the "Use" page for
2054 String. The getName() method in the java.awt.Font class returns type
2055 String. Therefore, getName() uses String, and you will find that
2056 method on the "Use" page for String.
2057 Note that this documents only uses of the API, not the implementa‐
2059 tion. If a method uses String in its implementation but does not
2060 take a string as an argument or return a string, that is not consid‐
2061 ered a "use" of String.
2062 You can access the generated "Use" page by first going to the class
2064 or package, then clicking on the "Use" link in the navigation bar.
2065 -version
2067 Includes the @version text in the generated docs. This text is
2068 omitted by default. To tell what version of the Javadoc tool you
2069 are using, use the -J-version option.
2070 -author
2072 Includes the @author text in the generated docs.
2073 -splitindex
2075 Splits the index file into multiple files, alphabetically, one
2076 file per letter, plus a file for any index entries that start
2077 with non-alphabetical characters.
2078 -windowtitle title
2080 Specifies the title to be placed in the HTML <title> tag. This
2081 appears in the window title and in any browser bookmarks
2082 (favorite places) that someone creates for this page. This title
2083 should not contain any HTML tags, as the browser will not prop‐
2084 erly interpret them. Any internal quotation marks within title
2085 may have to be escaped. If -windowtitle is omitted, the Javadoc
2086 tool uses the value of -doctitle for this option.
2087 % javadoc -windowtitle "Java 2 Platform" com.mypackage
2088 -doctitle title
2090 Specifies the title to be placed near the top of the overview
2091 summary file. The title will be placed as a centered, level-one
2092 heading directly beneath the upper navigation bar. The title may
2093 contain html tags and white space, though if it does, it must be
2094 enclosed in quotes. Any internal quotation marks within title may
2095 have to be escaped.
2096 % javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" com.mypackage
2097 -title title
2099 This option no longer exists. It existed only in Beta versions of
2100 Javadoc 1.2. It has been renamed to -doctitle. This option is
2101 being renamed to make it clear that it defines the document title
2102 rather than the window title.
2103 -header header
2105 Specifies the header text to be placed at the top of each output
2106 file. The header will be placed to the right of the upper naviga‐
2107 tion bar. header may contain HTML tags and white space, though if
2108 it does, it must be enclosed in quotes. Any internal quotation
2109 marks within header may have to be escaped.
2110 % javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage
2111 -footer footer
2113 Specifies the footer text to be placed at the bottom of each out‐
2114 put file. The footer will be placed to the right of the lower
2115 navigation bar. footer may contain html tags and white space,
2116 though if it does, it must be enclosed in quotes. Any internal
2117 quotation marks within footer may have to be escaped.
2118 -bottom text
2120 Specifies the text to be placed at the bottom of each output
2121 file. The text will be placed at the bottom of the page, below
2122 the lower navigation bar. The text may contain HTML tags and
2123 white space, though if it does, it must be enclosed in quotes.
2124 Any internal quotation marks within text may have to be escaped.
2125 -link extdocURL
2127 Creates links to existing javadoc-generated documentation of
2128 external referenced classes. It takes one argument:
2129 o extdocURL is the absolute or relative URL of the directory con‐
2131 taining the external javadoc-generated documentation you want
2132 to link to. Examples are shown below. The package-list file
2133 must be found in this directory (otherwise, use -linkoffline).
2134 The Javadoc tool reads the package names from the package-list
2135 file and then links to those packages at that URL. When the
2136 Javadoc tool is run, the extdocURL value is copied literally
2137 into the <A HREF> links that are created. Therefore, extdocURL
2138 must be the URL to the directory, not to a file.
2139 You can use an absolute link for extdocURL to enable your docs to
2141 link to a document on any website, or can use a relative link to
2142 link only to a relative location. If relative, the value you pass
2143 in should be the relative path from the destination directory
2144 (specified with -d) to the directory containing the packages
2145 being linked to.
2146 When specifying an absolute link you normally use an http: link.
2148 However, if you want to link to a file system that has no web
2149 server, you can use a file: link -- however, do this only if
2150 everyone wanting to access the generated documentation shares the
2151 same file system.
2152 In all cases, and on all operating systems, you should use a for‐
2154 ward slash as the separator, whether the URL is absolute or rela‐
2155 tive, and "http:" or "file:" based (as specified in the URL Memo
2156 @
2157 http://www.ietf.org/rfc/rfc1738.txt).
2158 Absolute http: based link:
2160 -link http://<host>/<directory>/<directory>/.../<name>
2161 Absolute file: based link:
2163 -link file://<host>/<directory>/<directory>/.../<name>
2164 Relative link:
2166 -link <directory>/<directory>/.../<name>
2167 You can specify multiple -link options in a given javadoc run to
2169 link to multiple documents. Choosing between -linkoffline and -link:
2170 Use -link:
2171 o when using a relative path to the external API document, or
2173 o when using an absolute URL to the external API document, if
2175 your shell allows a program to open a connection to that URL
2176 for reading.
2177 Use -linkoffline:
2178 o when using an absolute URL to the external API document, if
2180 your shell does not allow a program to open a connection to
2181 that URL for reading. This can occur if you are behind a fire‐
2182 wall and the document you want to link to is on the other side.
2183 Example using absolute links to the external docs - Let's say you
2185 want to link to the java.lang, java.io and other Java 2 Platform
2186 packages at http://java.sun.com/j2se/1.5.0/docs/api @
2187 http://java.sun.com/j2se/1.5.0/docs/api, The following command gen‐
2188 erates documentation for the package com.mypackage with links to the
2189 Java 2 Platform packages. The generated documentation will contain
2190 links to the Object class, for example, in the class trees. (Other
2191 options, such as -sourcepath and -d, are not shown.)
2192 % javadoc -link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage
2193 Example using relative links to the external docs - Let's say you
2194 have two packages whose docs are generated in different runs of the
2195 Javadoc tool, and those docs are separated by a relative path. In
2196 this example, the packages are com.apipackage, an API, and com.spi‐
2197 package, an SPI (Service Provide Interface). You want the documenta‐
2198 tion to reside in docs/api/com/apipackage and docs/spi/com/spipack‐
2199 age. Assuming the API package documentation is already generated,
2200 and that docs is the current directory, you would document the SPI
2201 package with links to the API documentation by running:
2202 % javadoc -d ./spi -link ../api com.spipackage
2203 Notice the -link argument is relative to the destination directory
2205 (docs/spi).
2206 Details - The -link option enables you to link to classes referenced
2208 to by your code but not documented in the current javadoc run. For
2209 these links to go to valid pages, you must know where those HTML
2210 pages are located, and specify that location with extdocURL. This
2211 allows, for instance, third party documentation to link to java.*
2212 documentation on http://java.sun.com.
2213 Omit the -link option for javadoc to create links only to API within
2215 the documentation it is generating in the current run. (Without the
2216 -link option, the Javadoc tool does not create links to documenta‐
2217 tion for external references, because it does not know if or where
2218 that documentation exists.)
2219 This option can create links in several places in the generated doc‐
2221 umentation.
2222 Another use is for cross-links between sets of packages: Execute
2224 javadoc on one set of packages, then run javadoc again on another
2225 set of packages, creating links both ways between both sets.
2226 How a Class Must be Referenced - For a link to an external refer‐
2228 enced class to actually appear (and not just its text label), the
2229 class must be referenced in the following way. It is not sufficient
2230 for it to be referenced in the body of a method. It must be refer‐
2231 enced in either an import statement or in a declaration. Here are
2232 examples of how the class java.io.File can be referenced:
2233 o In any kind of import statement: by wildcard import, import
2235 explicitly by name, or automatically import for java.lang.*.
2236 For example, this would suffice:
2237 import java.io.*;
2238 In 1.3.x and 1.2.x, only an explicit import by name works -- a
2239 wildcard import statement does not work, nor does the automatic
2240 import java.lang.*.
2241 o In a declaration:
2243 void foo(File f) {}
2244 The reference and be in the return type or parameter type of a
2245 method, constructor, field, class or interface, or in an imple‐
2246 ments, extends or throws statement.
2247 An important corollary is that when you use the -link option, there
2249 may be many links that unintentionally do not appear due to this
2250 constraint. (The text would appear without a hypertext link.) You
2251 can detect these by the warnings they emit. The most innocuous way
2252 to properly reference a class and thereby add the link would be to
2253 import that class, as shown above.
2254 Package List - The -link option requires that a file named pack‐
2256 age-list, which is generated by the Javadoc tool, exist at the URL
2257 you specify with -link. The package-list file is a simple text file
2258 that lists the names of packages documented at that location. In the
2259 earlier example, the Javadoc tool looks for a file named pack‐
2260 age-list at the given URL, reads in the package names and then links
2261 to those packages at that URL.
2262 For example, the package list for the Java 2 Platform 5.0 API is
2264 located at http://java.sun.com/j2se/1.5.0/docs/api/package-list @
2265 http://java.sun.com/j2se/1.5.0/docs/api/package-list. and starts out
2266 as follows:
2267 java.applet
2268 java.awt
2269 java.awt.color
2270 java.awt.datatransfer
2271 java.awt.dnd
2272 java.awt.event
2273 java.awt.font
2274 etc.
2275 When javadoc is run without the -link option, when it encounters a
2277 name that belongs to an external referenced class, it prints the
2278 name with no link. However, when the -link option is used, the
2279 Javadoc tool searches the package-list file at the specified
2280 extdocURL location for that package name. If it finds the package
2281 name, it prefixes the name with extdocURL.
2282 In order for there to be no broken links, all of the documentation
2284 for the external references must exist at the specified URLs. The
2285 Javadoc tool will not check that these pages exist -- only that the
2286 package-list exists.
2287 Multiple Links - You can supply multiple -link options to link to
2289 any number of external generated documents. Javadoc 1.2 has a
2290 known bug which prevents you from supplying more than one -link com‐
2291 mand. This was fixed in 1.2.2.
2292 Specify a different link option for each external document to link
2294 to:
2295 % javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn
2297 com.mypackage
2298 where extdocURL1, extdocURL2, ... extdocURLn point respectively to
2300 the roots of external documents, each of which contains a file named
2301 package-list.
2302 Cross-links - Note that "bootstrapping" may be required when
2304 cross-linking two or more documents that have not previously been
2305 generated. In other words, if package-list does not exist for either
2306 document, when you run the Javadoc tool on the first document, the
2307 package-list will not yet exist for the second document. Therefore,
2308 to create the external links, you must re-generate the first docu‐
2309 ment after generating the second document.
2310 In this case, the purpose of first generating a document is to cre‐
2312 ate its package-list (or you can create it by hand it if you're cer‐
2313 tain of the package names). Then generate the second document with
2314 its external links. The Javadoc tool prints a warning if a needed
2315 external package-list file does not exist.
2316 -linkoffline extdocURL packagelistLoc
2318 This option is a variation of -link; they both create links to
2319 javadoc-generated documentation for external referenced classes.
2320 Use the -linkoffline option when linking to a document on the web
2321 when the Javadoc tool itself is "offline" -- that is, it cannot
2322 access the document through a web connection.
2323 More specifically, use -linkoffline if the external document's pack‐
2325 age-list file is not accessible or does not exist at the extdocURL
2326 location but does exist at a different location, which can be speci‐
2327 fied by packageListLoc (typically local). Thus, if extdocURL is
2328 accessible only on the World Wide Web, -linkoffline removes the con‐
2329 straint that the Javadoc tool have a web connection when generating
2330 the documentation.
2331 Another use is as a "hack" to update docs: After you have run
2333 javadoc on a full set of packages, then you can run javadoc again on
2334 onlya smaller set of changed packages, so that the updated files can
2335 be inserted back into the original set. Examples are given below.
2336 The -linkoffline option takes two arguments -- the first for the
2338 string to be embedded in the <a href> links, the second telling it
2339 where to find package-list:
2340 o extdocURL is the absolute or relative URL of the directory con‐
2342 taining the external javadoc-generated documentation you want
2343 to link to. If relative, the value should be the relative path
2344 from the destination directory (specified with -d) to the root
2345 of the packages being linked to. For more details, see
2346 extdocURL in the -link option.
2347 o packagelistLoc is the path or URL to the directory containing
2349 the package-list file for the external documentation. This can
2350 be a URL (http: or file:) or file path, and can be absolute or
2351 relative. If relative, make it relative to the current direc‐
2352 tory from where javadoc was run. Do not include the pack‐
2353 age-list filename.
2354 You can specify multiple -linkoffline options in a given javadoc
2356 run. (Prior to 1.2.2, it could be specified only once.)
2357 Example using absolute links to the external docs - Let's say you
2359 want to link to the java.lang, java.io and other Java 2 Platform
2360 packages at http://java.sun.com/j2se/1.5.0/docs/api, but your shell
2361 does not have web access. You could open the package-list file in a
2362 browser at http://java.sun.com/j2se/1.5.0/docs/api/package-list @
2363 http://java.sun.com/j2se/1.5.0/docs/api/package-list, save it to a
2364 local directory, and point to this local copy with the second argu‐
2365 ment, packagelistLoc. In this example, the package list file has
2366 been saved to the current directory "." . The following command gen‐
2367 erates documentation for the package com.mypackage with links to the
2368 Java 2 Platform packages. The generated documentation will contain
2369 links to the Object class, for example, in the class trees. (Other
2370 necessary options, such as -sourcepath, are not shown.)
2371 % javadoc -linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage
2372 Example using relative links to the external docs - It's not very
2374 common to use -linkoffline with relative paths, for the simple rea‐
2375 son that -link usually suffices. When using -linkoffline, the pack‐
2376 age-list file is generally local, and when using relative links, the
2377 file you are linking to is also generally local. So it is usually
2378 unnecessary to give a different path for the two arguments to
2379 -linkoffline. When the two arguments are identical, you can use
2380 -link. See the -link relative example.
2381 Manually Creating a package-list File - If a package-list file does
2383 not yet exist, but you know what package names your document will
2384 link to, you can create your own copy of this file by hand and spec‐
2385 ify its path with packagelistLoc. An example would be the previous
2386 case where the package list for com.spipackage did not exist when
2387 com.apipackage was first generated. This technique is useful when
2388 you need to generate documentation that links to new external docu‐
2389 mentation whose package names you know, but which is not yet pub‐
2390 lished. This is also a way of creating package-list files for pack‐
2391 ages generated with Javadoc 1.0 or 1.1, where package-list files
2392 were not generated. Likewise, two companies can share their unpub‐
2393 lished package-list files, enabling them to release their
2394 cross-linked documentation simultaneously.
2395 Linking to Multiple Documents - You can include -linkoffline once
2397 for each generated document you want to refer to (each option is
2398 shown on a separate line for clarity):
2399 % javadoc -linkoffline extdocURL1 packagelistLoc1 \
2401 -linkoffline extdocURL2 packagelistLoc2 \
2402 ...
2403 Updating docs - Another use for -linkoffline option is useful if
2405 your project has dozens or hundreds of packages, if you have already
2406 run javadoc on the entire tree, and now, in a separate run, you want
2407 to quickly make some small changes and re-run javadoc on just a
2408 small portion of the source tree. This is somewhat of a hack in that
2409 it works properly only if your changes are only to doc comments and
2410 not to declarations. If you were to add, remove or change any decla‐
2411 rations from the source code, then broken links could show up in the
2412 index, package tree, inherited member lists, use page, and other
2413 places.
2414 First, you create a new destination directory (call it update) for
2416 this new small run. Let's say the original destination directory was
2417 named html. In the simplest example, cd to the parent of html. Set
2418 the first argument of -linkoffline to the current directory "." and
2419 set the second argument to the relative path to html, where it can
2420 find package-list, and pass in only the package names of the pack‐
2421 ages you want to update:
2422 % javadoc -d update -linkoffline . html com.mypackage
2423 When the Javadoc tool is done, copy these generated class pages in
2424 update/com/package (not the overview or index), over the original
2425 files in html/com/package.
2426 -linksource
2428 Creates an HTML version of each source file (with line numbers)
2429 and adds links to them from the standard HTML documentation.
2430 Links are created for classes, interfaces, constructors, methods
2431 and fields whose declarations are in a source file. Otherwise,
2432 links are not created, such as for default constructors and gen‐
2433 erated classes.
2434 This option exposes all private implementation details in the
2436 included source files, including private classes, private fields,
2437 and the bodies of private methods, regardless of the -public, -pack‐
2438 age, -protected and -private options. Unless you also use the -pri‐
2439 vate option, not all private classes or interfaces will necessarily
2440 be accessible via links.
2441 Each link appears on the name of the identifier in its declaration.
2443 For example, the link to the source code of the Button class would
2444 be on the word "Button":
2445 public class Button
2446 extends Component
2447 implements Accessible
2448 and the link to the source code of the getLabel() method in the But‐
2449 ton class would be on the word "getLabel":
2450 public String getLabel()
2451 -group groupheading packagepattern:packagepattern:...
2453 Separates packages on the overview page into whatever groups you
2454 specify, one group per table. You specify each group with a dif‐
2455 ferent -group option. The groups appear on the page in the order
2456 specified on the command line; packages are alphabetized within a
2457 group. For a given -group option, the packages matching the list
2458 of packagepattern expressions appear in a table with the heading
2459 groupheading.
2460 o groupheading can be any text, and can include white space. This
2462 text is placed in the table heading for the group.
2463 o packagepattern can be any package name, or can be the start of
2465 any package name followed by an asterisk (*). The asterisk is a
2466 wildcard meaning "match any characters". This is the only wild‐
2467 card allowed. Multiple patterns can be included in a group by
2468 separating them with colons (:).
2469 NOTE: If using an asterisk in a pattern or pattern list, the pat‐
2472 tern list must be inside quotes, such as "java.lang*:java.util"
2473 If you do not supply any -group option, all packages are placed in
2475 one group with the heading "Packages". If the all groups do not
2476 include all documented packages, any leftover packages appear in a
2477 separate group with the heading "Other Packages".
2478 For example, the following option separates the four documented
2480 packages into core, extension and other packages. Notice the trail‐
2481 ing "dot" does not appear in "java.lang*" -- including the dot, such
2482 as "java.lang.*" would omit the java.lang package.
2483 % javadoc -group "Core Packages" "java.lang*:java.util"
2484 -group "Extension Packages" "javax.*"
2485 java.lang java.lang.reflect java.util javax.servlet java.new
2486 This results in the groupings:
2487 Core Packages
2489 java.lang java.lang.reflect java.util
2490 Extension Packages
2492 javax.servlet
2493 Other Packages
2495 java.new
2496 -nodeprecated
2499 Prevents the generation of any deprecated API at all in the docu‐
2500 mentation. This does what -nodeprecatedlist does, plus it does
2501 not generate any deprecated API throughout the rest of the docu‐
2502 mentation. This is useful when writing code and you don't want to
2503 be distracted by the deprecated code.
2504 -nodeprecatedlist
2506 Prevents the generation of the file containing the list of depre‐
2507 cated APIs (deprecated-list.html) and the link in the navigation
2508 bar to that page. (However, javadoc continues to generate the
2509 deprecated API throughout the rest of the document.) This is use‐
2510 ful if your source code contains no deprecated API, and you want
2511 to make the navigation bar cleaner.
2512 -nosince
2514 Omits from the generated docs the "Since" sections associated
2515 with the @since tags.
2516 -notree
2518 Omits the class/interface hierarchy pages from the generated
2519 docs. These are the pages you reach using the "Tree" button in
2520 the navigation bar. The hierarchy is produced by default.
2521 -noindex
2523 Omits the index from the generated docs. The index is produced by
2524 default.
2525 -nohelp
2527 Omits the HELP link in the navigation bars at the top and bottom
2528 of each page of output.
2529 -nonavbar
2531 Prevents the generation of the navigation bar, header and footer,
2532 otherwise found at the top and bottom of the generated pages. Has
2533 no affect on the "bottom" option. The -nonavbar option is useful
2534 when you are interested only in the content and have no need for
2535 navigation, such as converting the files to PostScript or PDF for
2536 print only.
2537 -helpfile path/filename
2539 Specifies the path of an alternate help file path/filename that
2540 the HELP link in the top and bottom navigation bars link to.
2541 Without this option, the Javadoc tool automatically creates a
2542 help file help-doc.html that is hard-coded in the Javadoc tool.
2543 This option enables you to override this default. The filename
2544 can be any name and is not restricted to help-doc.html -- the
2545 Javadoc tool will adjust the links in the navigation bar accord‐
2546 ingly. For example:
2547 % javadoc -helpfile /home/user/myhelp.html java.awt
2548 -stylesheetfile path/filename
2550 Specifies the path of an alternate HTML stylesheet file. Without
2551 this option, the Javadoc tool automatically creates a stylesheet
2552 file stylesheet.css that is hard-coded in the Javadoc tool. This
2553 option enables you to override this default. The filename can be
2554 any name and is not restricted to stylesheet.css. For example:
2555 % javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage
2556 -serialwarn
2558 Generates compile-time warnings for missing @serial tags. By
2559 default, Javadoc 1.2.2 (and later versions) generates no serial
2560 warnings. (This is a reversal from earlier versions.) Use this
2561 option to display the serial warnings, which helps to properly
2562 document default serializable fields and writeExternal methods.
2563 -charset name
2565 Specifies the HTML character set for this document. The name
2566 should be a preferred MIME name as given in the IANA Registry @
2567 http://www.iana.org/assignments/character-sets. For example:
2568 % javadoc -charset "iso-8859-1" mypackage
2569 would insert the following line in the head of every generated
2570 page:
2571 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2572 This META tag is described in the HTML standard @
2573 http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2. (4197265
2574 and 4137321)
2575 Also see -encoding and -docencoding.
2577 -docencoding name
2579 Specifies the encoding of the generated HTML files. The name
2580 should be a preferred MIME name as given in the IANA Registry @
2581 http://www.iana.org/assignments/character-sets. If you omit this
2582 option but use -encoding, then the encoding of the generated HTML
2583 files is determined by -encoding. Example:
2584 % javadoc -docencoding "ISO-8859-1" mypackage
2585 Also see -encoding and -charset.
2586 -keywords
2588 Adds HTML meta keyword tags to the generated file for each class.
2589 These tags can help the page be found by search engines that look
2590 for meta tags. (Most search engines that search the entire Inter‐
2591 net do not look at meta tags, because pages can misuse them; but
2592 search engines offered by companies that confine their search to
2593 their own website can benefit by looking at meta tags.)
2594 The meta tags include the fully qualified name of the class and the
2596 unqualified names of the fields and methods. Constructors are not
2597 included because they are identical to the class name. For example,
2598 the class String starts with these keywords:
2599 <META NAME="keywords" CONTENT="java.lang.String class">
2600 <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
2601 <META NAME="keywords" CONTENT="length()">
2602 <META NAME="keywords" CONTENT="charAt()">
2603 -tag tagname:Xaoptcmf:"taghead"
2605 Enables the Javadoc tool to interpret a simple, one-argument cus‐
2606 tom block tag @tagname in doc comments. So the Javadoc tool can
2607 "spell-check" tag names, it is important to include a -tag option
2608 for every custom tag that is present in the source code, dis‐
2609 abling (with X) those that are not being output in the current
2610 run.
2611 The colon (:) is always the separator. To use a colon in tagname,
2613 see Use of Colon in Tag Name.
2614 The -tag option outputs the tag's heading taghead in bold, followed
2616 on the next line by the text from its single argument, as shown in
2617 the example below. Like any block tag, this argument's text can con‐
2618 tain inline tags, which are also interpreted. The output is similar
2619 to standard one-argument tags, such as @return and @author. Omitting
2620 taghead causes tagname to appear as the heading.
2621 Placement of tags - The Xaoptcmf part of the argument determines
2623 where in the source code the tag is allowed to be placed, and
2624 whether the tag can be disabled (using X). You can supply either a,
2625 to allow the tag in all places, or any combination of the other let‐
2626 ters: X (disable tag)
2627 a (all)
2628 o (overview)
2629 p (packages)
2630 t (types, that is classes and interfaces)
2631 c (constructors)
2632 m (methods)
2633 f (fields)
2634 Examples of single tags - An example of a tag option for a tag that
2636 that can be used anywhere in the source code is:
2637 -tag todo:a:"To Do:"
2638 If you wanted @todo to be used only with constructors, methods and
2639 fields, you would use:
2640 -tag todo:cmf:"To Do:"
2641 Notice the last colon (:) above is not a parameter separator, but is
2642 part of the heading text (as shown below). You would use either tag
2643 option for source code that contains the tag @todo, such as:
2644 @todo The documentation for this method needs work.
2645 Use of Colon in Tag Name - A colon can be used in a tag name if it
2646 is escaped with a backslash. For this doc comment:
2647 /**
2648 * @ejb:bean
2649 */
2650 use this tag option:
2651 -tag ejb\\:bean:a:"EJB Bean:"
2652 Spell-checking tag names (Disabling tags) - Some developers put cus‐
2653 tom tags in the source code that they don't always want to output.
2654 In these cases, it is important to list all tags that are present in
2655 the source code, enabling the ones you want to output and disabling
2656 the ones you don't want to output. The presence of X disables the
2657 tag, while its absence enables the tag. This gives the Javadoc tool
2658 enough information to know if a tag it encounters is unknown, proba‐
2659 bly the results of a typo or a misspelling. It prints a warning in
2660 these cases.
2661 You can add X to the placement values already present, so that when
2663 you want to enable the tag, you can simply delete the X. For exam‐
2664 ple, if @todo is a tag that you want to suppress on output, you
2665 would use:
2666 -tag todo:Xcmf:"To Do:"
2667 or, if you'd rather keep it simple:
2668 -tag todo:X
2669 The syntax -tag todo:X works even if @todo is defined by a taglet.
2671 Order of tags - The order of the -tag (and -taglet) options deter‐
2673 mine the order the tags are output. You can mix the custom tags with
2674 the standard tags to intersperse them. The tag options for standard
2675 tags are placeholders only for determining the order -- they take
2676 only the standard tag's name. (Subheadings for standard tags cannot
2677 be altered.) This is illustrated in the following example.
2678 If -tag is missing, then the position of -taglet determines its
2680 order. If they are both present, then whichever appears last on the
2681 command line determines its order. (This happens because the tags
2682 and taglets are processed in the order that they appear on the com‐
2683 mand line. For example, if -taglet and -tag both have the name
2684 "todo", the one that appears last on the command line will determine
2685 its order.
2686 Example of a complete set of tags - This example inserts "To Do"
2688 after "Parameters" and before "Throws" in the output. By using "X",
2689 it also specifies that @example is a tag that might be encountered
2690 in the source code that should not be output during this run. Notice
2691 that if you use @argfile, you can put the tags on separate lines in
2692 an argument file like this (no line continuation characters needed):
2693 -tag param
2694 -tag return
2695 -tag todo:a:"To Do:"
2696 -tag throws
2697 -tag see
2698 -tag example:X
2699 When javadoc parses the doc comments, any tag encountered that is
2701 neither a standard tag nor passed in with -tag or -taglet is consid‐
2702 ered unknown, and a warning is thrown.
2703 The standard tags are initially stored internally in a list in their
2705 default order. Whenever -tag options are used, those tags get
2706 appended to this list -- standard tags are moved from their default
2707 position. Therefore, if a -tag option is omitted for a standard tag,
2708 it remains in its default position.
2709 Avoiding Conflicts - If you want to slice out your own namespace,
2711 you can use a dot-separated naming convention similar to that used
2712 for packages: com.mycompany.todo. Sun will continue to create stan‐
2713 dard tags whose names do not contain dots. Any tag you create will
2714 override the behavior of a tag by the same name defined by Sun. In
2715 other words, if you create a tag or taglet @todo, it will always
2716 have the same behavior you define, even if Sun later creates a stan‐
2717 dard tag of the same name.
2718 Annotations vs. Javadoc Tags - In general, if the markup you want to
2720 add is intended to affect or produce documentation, it should proba‐
2721 bly be a javadoc tag; otherwise, it should be an annotation. See
2722 Comparing Annotations and Javadoc Tags @
2723 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#anno‐
2724 tations
2725 You can also create more complex block tags, or custom inline tags
2727 with the -taglet option.
2728 -taglet class
2730 Specifies the class file that starts the taglet used in generat‐
2731 ing the documentation for that tag. Use the fully-qualified name
2732 for class. This taglet also defines the number of text arguments
2733 that the custom tag has. The taglet accepts those arguments, pro‐
2734 cesses them, and generates the output. For extensive documenta‐
2735 tion with example taglets, see:
2736 o Taglet Overview
2738 Taglets are useful for block or inline tags. They can have any num‐
2740 ber of arguments and implement custom behavior, such as making text
2741 bold, formatting bullets, writing out the text to a file, or start‐
2742 ing other processes.
2743 Taglets can only determine where a tag should appear and in what
2745 form. All other decisions are made by the doclet. So a taglet cannot
2746 do things such as remove a class name from the list of included
2747 classes. However, it can execute side effects, such as printing the
2748 tag's text to a file or triggering another process.
2749 Use the -tagletpath option to specify the path to the taglet. Here
2751 is an example that inserts the "To Do" taglet after "Parameters" and
2752 ahead of "Throws" in the generated pages:
2753 -taglet com.sun.tools.doclets.ToDoTaglet
2754 -tagletpath /home/taglets
2755 -tag return
2756 -tag param
2757 -tag todo
2758 -tag throws
2759 -tag see
2760 Alternatively, you can use the -taglet option in place of its -tag
2762 option, but that may be harder to read.
2763 -tagletpath tagletpathlist
2765 Specifies the search paths for finding taglet class files
2766 (.class). The tagletpathlist can contain multiple paths by sepa‐
2767 rating them with a colon (:). The Javadoc tool will search in all
2768 subdirectories of the specified paths.
2769 -docfilessubdirs
2771 Enables deep copying of "doc-files" directories. In other words,
2772 subdirectories and all contents are recursively copied to the
2773 destination. For example, the directory doc-files/example/images
2774 and all its contents would now be copied. There is also an option
2775 to exclude subdirectories.
2776 -excludedocfilessubdir name1:name2...
2778 Excludes any "doc-files" subdirectories with the given names.
2779 This prevents the copying of SCCS and other source-code-control
2780 subdirectories.
2781 -noqualifier all | packagename1:packagename2:...
2783 Omits qualifying package name from ahead of class names in out‐
2784 put. The argument to -noqualifier is either "all" (all package
2785 qualifiers are omitted) or a colon-separate list of packages,
2786 with wildcards, to be removed as qualifiers. The package name is
2787 removed from places where class or interface names appear.
2788 The following example omits all package qualifiers:
2790 -noqualifier all
2791 The following example omits "java.lang" and "java.io" package quali‐
2792 fiers:
2793 -noqualifier java.lang:java.io
2794 The following example omits package qualifiers starting with "java",
2795 and "com.sun" subpackages (but not "javax"):
2796 -noqualifier java.*:com.sun.*
2797 Where a package qualifier would appear due to the above behavior,
2798 the name can be suitably shortened -- see How a name is displayed.
2799 This rule is in effect whether or not -noqualifier is used.
2800 -notimestamp
2802 Suppresses the timestamp, which is hidden in an HTML comment in
2803 the generated HTML near the top of each page. Useful when you
2804 want to run javadoc on two source bases and diff them, as it pre‐
2805 vents timestamps from causing a diff (which would otherwise be a
2806 diff on every page). The timestamp includes the javadoc version
2807 number, and currently looks like this:
2808 <!-- Generated by javadoc (build 1.5.0-internal) on Tue Jun 22 09:57:24 PDT 2004 -->
2809 -nocomment
2811 Suppress the entire comment body, including the main description
2812 and all tags, generating only declarations. This option enables
2813 re-using source files originally intended for a different pur‐
2814 pose, to produce skeleton HTML documentation at the early stages
2815 of a new project.
2816
2818 To shorten or simplify the javadoc command line, you can specify one or
2819 more files that themselves contain arguments to the javadoc command
2820 (except -J options). This enables you to create javadoc commands of any
2821 length on any operating system.
2822 An argument file can include javac options and source filenames in any
2824 combination. The arguments within a file can be space-separated or new‐
2825 line-separated. If a filename contains embedded spaces, put the whole
2826 filename in double quotes.
2827 Filenames within an argument file are relative to the current direc‐
2829 tory, not the location of the argument file. Wildcards (*) are not
2830 allowed in these lists (such as for specifying *.java). Use of the '@'
2831 character to recursively interpret files is not supported. The -J
2832 options are not supported because they are passed to the launcher,
2833 which does not support argument files.
2834 When executing javadoc, pass in the path and name of each argument file
2836 with the '@' leading character. When javadoc encounters an argument
2837 beginning with the character `@', it expands the contents of that file
2838 into the argument list.
2839 Example - Single Arg File
2841 You could use a single argument file named "argfile" to hold all
2842 Javadoc arguments:
2843 % javadoc @argfile
2845 This argument file could contain the contents of both files shown in
2848 the next example.
2849 Example - Two Arg Files
2851 You can create two argument files -- one for the Javadoc options and
2852 the other for the package names or source filenames: (Notice the fol‐
2853 lowing lists have no line-continuation characters.)
2854 Create a file named "options" containing:
2856 -d docs-filelist
2858 -use
2859 -splitindex
2860 -windowtitle 'Java 2 Platform v1.3 API Specification'
2861 -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification'
2862 -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>'
2863 -bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.'
2864 -group "Core Packages" "java.*"
2865 -overview /java/pubs/ws/1.5/src/share/classes/overview-core.html
2866 -sourcepath /java/pubs/ws/1.5/src/share/classes
2867 Create a file named "packages" containing:
2870 com.mypackage1
2872 com.mypackage2
2873 com.mypackage3
2874 You would then run javadoc with:
2877 % javadoc @options @packages
2879 Example - Arg Files with Paths
2882 The argument files can have paths, but any filenames inside the files
2883 are relative to the current working directory (not path1 or path2):
2884 % javadoc @path1/options @path2/packages
2886 Example - Option Arguments
2889 Here's an example of saving just an argument to a javadoc option in an
2890 argument file. We'll use the -bottom option, since it can have a
2891 lengthy argument. You could create a file named "bottom" containing its
2892 text argument:
2893 bug or feature</a><br><br>Java is a trademark or registered trademark of
2895 Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun
2896 Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
2897 All Rights Reserved.</font>'
2898 Then run the Javadoc tool with:
2901 % javadoc -bottom @bottom @packages
2903 Or you could include the -bottom option at the start of the argument
2906 file, and then just run it as:
2907 % javadoc @bottom @packages
2909
2911 Running
2912
2914 Version Numbers - The version number of javadoc can be determined using
2915 javadoc -J-version. The version number of the standard doclet appears
2916 in its output stream. It can be turned off with -quiet.
2917 Public programmatic interface - To invoke the Javadoc tool from within
2919 programs written in the Java language. This interface is in
2920 com.sun.tools.javadoc.Main (and javadoc is re-entrant). For more
2921 details, see Standard Doclet.
2922 Running Doclets - The instructions given below are for invoking the
2924 standard HTML doclet. To invoke a custom doclet, use the -doclet and
2925 -docletpath options. For full, working examples of running a particular
2926 doclet, see Running the MIF Doclet @
2927 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#running‐
2928 mifdoclet.
2929
2931 You can run javadoc on entire packages or individual source files. Each
2932 package name has a corresponding directory name. In the following exam‐
2933 ples, the source files are located at /home/src/java/awt/*.java. The
2934 destination directory is /home/html.
2935 Documenting One or More Packages
2937 To document a package, the source files (*.java) for that package must
2938 be located in a directory having the same name as the package. If a
2939 package name is made up of several identifiers (separated by dots, such
2940 as java.awt.color), each subsequent identifier must correspond to a
2941 deeper subdirectory (such as java/awt/color). You may split the source
2942 files for a single package among two such directory trees located at
2943 different places, as long as -sourcepath points to them both -- for
2944 example src1/java/awt/color and src2/java/awt/color.
2945 You can run javadoc either by changing directories (with cd) or by
2947 using -sourcepath option. The examples below illustrate both alterna‐
2948 tives.
2949 o Case 1 - Run recursively starting from one or more packages - This
2951 example uses -sourcepath so javadoc can be run from any directory
2952 and -subpackages (a new 1.4 option) for recursion. It traverses
2953 the subpackages of the java directory excluding packages rooted at
2954 java.net and java.lang. Notice this excludes java.lang.ref, a sub‐
2955 package of java.lang).
2956 % javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang
2957 To also traverse down other package trees, append their names to the
2959 -subpackages argument, such as java:javax:org.xml.sax.
2960 o Case 2 - Run on explicit packages after changing to the "root"
2962 source directory - Change to the parent directory of the
2963 fully-qualified package. Then run javadoc, supplying names of one
2964 or more packages you want to document:
2965 % cd /home/src/
2966 % javadoc -d /home/html java.awt java.awt.event
2967 o Case 3 - Run from any directory on explicit packages in a single
2969 directory tree - In this case, it doesn't matter what the current
2970 directory is. Run javadoc supplying -sourcepath with the parent
2971 directory of the top-level package, and supplying names of one or
2972 more packages you want to document:
2973 % javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
2974 o Case 4 - Run from any directory on explicit packages in multiple
2976 directory trees - This is the same as case 3, but for packages in
2977 separate directory trees. Run javadoc supplying -sourcepath with
2978 the path to each tree's root (colon-separated) and supply names of
2979 one or more packages you want to document. All source files for a
2980 given package do not need to be located under a single root direc‐
2981 tory -- they just need to be found somewhere along the sourcepath.
2982 % javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
2983 Result: All cases generate HTML-formatted documentation for the public
2986 and protected classes and interfaces in packages java.awt and
2987 java.awt.event and save the HTML files in the specified destination
2988 directory (/home/html). Because two or more packages are being gener‐
2989 ated, the document has three HTML frames -- for the list of packages,
2990 the list of classes, and the main class pages.
2991 Documenting One or More Classes
2993 The second way to run the Javadoc tool is by passing in one or more
2994 source files (.java). You can run javadoc either of the following two
2995 ways -- by changing directories (with cd) or by fully-specifying the
2996 path to the .java files. Relative paths are relative to the current
2997 directory. The -sourcepath option is ignored when passing in source
2998 files. You can use command line wildcards, such as asterisk (*), to
2999 specify groups of classes.
3000 o Case 1 - Changing to the source directory - Change to the direc‐
3002 tory holding the .java files. Then run javadoc, supplying names of
3003 one or more source files you want to document.
3004 % cd /home/src/java/awt
3005 % javadoc -d /home/html Button.java Canvas.java Graphics*.java
3006 This example generates HTML-formatted documentation for the
3007 classes Button, Canvas and classes beginning with Graphics.
3008 Because source files rather than package names were passed in as
3009 arguments to javadoc, the document has two frames -- for the list
3010 of classes and the main page.
3011 o Case 2 - Changing to the package root directory - This is useful
3013 for documenting individual source files from different subpackages
3014 off the same root. Change to the package root directory, and sup‐
3015 ply the source files with paths from the root.
3016 % cd /home/src/
3017 % javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
3018 This example generates HTML-formatted documentation for the
3019 classes Button and Applet.
3020 o Case 3 - From any directory - In this case, it doesn't matter what
3022 the current directory is. Run javadoc supplying the absolute path
3023 (or path relative to the current directory) to the .java files you
3024 want to document.
3025 % javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
3026 This example generates HTML-formatted documentation for the class
3027 Button and classes beginning with Graphics.
3028 Documenting Both Packages and Classes
3031 You can document entire packages and individual classes at the same
3032 time. Here's an example that mixes two of the previous examples. You
3033 can use -sourcepath for the path to the packages but not for the path
3034 to the individual classes.
3035 % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java
3037 This example generates HTML-formatted documentation for the package
3040 java.awt and class Applet. (The Javadoc tool determines the package
3041 name for Applet from the package declaration, if any, in the
3042 Applet.java source file.)
3043
3045 The Javadoc tool has many useful options, some of which are more com‐
3046 monly used than others. Here is effectively the command we use to run
3047 the Javadoc tool on the Java platform API. We use 180MB of memory to
3048 generate the documentation for the 1500 (approx.) public and protected
3049 classes in the Java 2 Platform, Standard Edition, v1.2.
3050 The same example is shown twice -- first as executed on the command
3052 line, then as executed from a makefile. It uses absolute paths in the
3053 option arguments, which enables the same javadoc command to be run from
3054 any directory.
3055 Command Line Example
3057 This command line example is over 900 characters, which is too long for
3058 some shells, such as DOS. You can use a command line argument file (or
3059 write a shell script) to workaround this limitation.
3060 % javadoc -sourcepath /java/jdk/src/share/classes \
3062 -overview /java/jdk/src/share/classes/overview.html \
3063 -d /java/jdk/build/api \
3064 -use \
3065 -splitIndex \
3066 -windowtitle 'Java 2 Platform 5.0 API Specification' \
3067 -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification' \
3068 -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>' \
3069 -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
3070 a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems,
3071 Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc.
3072 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' \
3073 -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
3074 -group "Extension Packages" "javax.*" \
3075 -J-Xmx180m \
3076 @packages
3077 where packages is the name of a file containing the packages to
3080 process, such as java.applet java.lang. None of the options should con‐
3081 tain any newline characters between the single quotes. (For example, if
3082 you copy and paste this example, delete the newline characters from the
3083 -bottom option.) See the other notes listed below.
3084 Makefile Example
3086 This is an example of a GNU makefile. For an example of a Windows make‐
3087 file, see creating a makefile for Windows @
3088 http://java.sun.com/j2se/javadoc/faq/index.html#makefiles.
3089 javadoc -sourcepath $(SRCDIR) \ /* Sets path for source files */
3091 -overview $(SRCDIR)/overview.html \ /* Sets file for overview text */
3092 -d /java/jdk/build/api \ /* Sets destination directory */
3093 -use \ /* Adds "Use" files */
3094 -splitIndex \ /* Splits index A-Z */
3095 -windowtitle $(WINDOWTITLE) \ /* Adds a window title */
3096 -doctitle $(DOCTITLE) \ /* Adds a doc title */
3097 -header $(HEADER) \ /* Adds running header text */
3098 -bottom $(BOTTOM) \ /* Adds text at bottom */
3099 -group $(GROUPCORE) \ /* 1st subhead on overview page */
3100 -group $(GROUPEXT) \ /* 2nd subhead on overview page */
3101 -J-Xmx180m \ /* Sets memory to 180MB */
3102 java.lang java.lang.reflect \ /* Sets packages to document */
3103 java.util java.io java.net \
3104 java.applet
3105 WINDOWTITLE = 'Java 2 Platform v1.2 API Specification'
3107 DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification'
3108 HEADER = '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>'
3109 BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
3110 a bug or feature</a><br><br>Java is a trademark or registered trademark
3111 of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1999
3112 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
3113 All Rights Reserved.</font>'
3114 GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
3115 GROUPEXT = '"Extension Packages" "javax.*"'
3116 SRCDIR = '/java/jdk/1.2/src/share/classes'
3117 Single quotes are used to surround makefile arguments.
3120 NOTES
3122 o If you omit the -windowtitle option, the Javadoc tool copies the
3124 doc title to the window title. The -windowtitle text is basically
3125 the same as the -doctitle but without HTML tags, to prevent those
3126 tags from appearing as raw text in the window title.
3127 o If you omit the -footer option, as done here, the Javadoc tool
3129 copies the header text to the footer.
3130 o Other important options you might want to use but not needed in
3132 this example are -classpath and -link.
3133
3136 General Troubleshooting
3137 o Javadoc FAQ - Commonly-encountered bugs and troubleshooting tips
3138 can be found on the Javadoc FAQ @
3139 http://java.sun.com/j2se/javadoc/faq/index.html#B
3140 o Bugs and Limitations - You can also see some bugs listed at Impor‐
3142 tant Bug Fixes and Changes @
3143 http://java.sun.com/j2se/1.5.0/fixedbugs/index.html.
3144 o Version number - See version numbers.
3146 o Documents only legal classes - When documenting a package, javadoc
3148 only reads files whose names are composed of legal class names.
3149 You can prevent javadoc from parsing a file by including, for
3150 example, a hyphen "-" in its filename.
3151 Errors and Warnings
3154 Error and warning messages contain the filename and line number to the
3155 declaration line rather than to the particular line in the doc comment.
3156 o "error: cannot read: Class1.java" the Javadoc tool is trying to
3158 load the class Class1.java in the current directory. The class
3159 name is shown with its path (absolute or relative), which in this
3160 case is the same as ./Class1.java.
3161
3164 CLASSPATH
3165 Environment variable that provides the path which javadoc uses to
3166 find user class files. This environment variable is overridden by
3167 the -classpath option. Separate directories with a colon, for
3168 example:
3169
3172 o javac
3173 o java
3175 o jdb
3177 o javah
3179 o javap
3181 o Javadoc Home Page @
3183 http://java.sun.com/j2se/javadoc/index.jsp
3184 o How to Write Doc Comments for Javadoc @
3186 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
3187 o Setting the Class Path
3189 o How Javac and Javadoc Find Classes (tools.jar)
3191 Javadoc is a trademark of Sun Microsystems, Inc. (The javadoc command
3194 itself does not require the trademark symbol.)
3195 07 Aug 2006 javadoc(1)