javadoc - Unix, Linux Command
NAME
javadoc - Java API documentation generator
SYNOPSIS
javadoc [
options ] [
packagenames ] [
sourcefilenames ] [
-subpackages pkg1:pkg2:... ] [
@argfiles ]
PARAMETERS
Arguments can be in any order.
Tag | Description |
options |
Command-line options, as specified in this
document.
To see a typical use of
javadoc options, see Real World Example.
|
packagenames |
A series of names of packages, separated by spaces,
such as
java.lang java.lang.reflect java.awt. You must separately specify each package you want to document.
The
Javadoc tool uses
-sourcepath to look for these package names.
The
Javadoc tool does not recursively traverse subpackages.
Wildcards such as asterisks (*) are not allowed.
See
EXAMPLES, Documenting One or More Packages.
|
sourcefilenames |
A series of source file names, separated by spaces,
each of which can include paths and wildcards such as
asterisk (*).
The
Javadoc tool will process every file whose name ends with
.java , and whose name, when stripped of that suffix, is actually a
legal class name (see Identifiers).
Therefore, you can name files with dashes (such as X-Buffer),
or other illegal characters, to prevent them from being documented.
This is useful for test files and files generated from templates.
The path that
precedes the source file name determines where
javadoc will look for the file.
The
Javadoc tool does not use
-sourcepath to look for these source file names.)
For example, passing in
Button.java is identical to
./Button.java. An example source file name with a
full path is
/home/src/java/awt/Graphics*.java. See
EXAMPLES, Documenting One or More Classes.
You can
also mix
packagenames and
sourcefilenames, as in
EXAMPLES, Documenting Both Packages and Classes.
|
-subpackages pkg1:pkg2:... | |
Generates documentation from source files in the specified
packages and recursively in their subpackages. An alternative
to supplying packagenames or sourcefilenames.
|
@argfiles |
One or more files that contain a list of Javadoc options,
packagenames and
sourcefilenames in any order. Wildcards (*) and
-J options are not allowed in these files.
|
DESCRIPTION
The
Javadoc tool parses the declarations and documentation comments in a
set of Java source files and produces a corresponding set of HTML
pages describing (by default) the public and protected classes,
nested classes (but not anonymous inner classes),
interfaces, constructors, methods, and fields.
You can run the
Javadoc tool on entire packages, individual source files, or both.
In the first case, you pass in as an argument to
javadoc a series of package names.
In the second case, you pass in a series
of source (.java) file names.
See
EXAMPLES at the end of this document.
NOTE - When you pass in package names to the Javadoc tool, it currently processes all
.java classes in the specified package directories, even if the
.java files are code examples or other classes that are not
actually members of the specified packages. It does not parse each
.java file for a package declaration; we may add this parsing in
a future release.
During a run, the Javadoc tool automatically adds cross-reference links to
package, class and member names that are being documented as part
of that run. Links appear in several places:
o
Declarations (return types, argument types, field types)
Tag | Description |
o
|
"See Also" sections generated from @see tags
|
o
|
In-line text generated from {@link} tags
|
o
|
Exception names generated from @throws tags
|
o
|
Specified by links to members in interfaces and Overrides links
to members in classes
|
o
|
Summary tables listing packages, classes and members
|
o
|
Package and class inheritance trees
|
o
|
The index
|
You can add hyperlinks to existing text for classes not included on the
command line (but generated separately) by way of the -link
and -linkoffline options.
The Javadoc tool produces one complete document each time it is run; it
cannot do incremental builds - that is, it cannot modify or
directly incorporate results from previous runs of Javadoc. However, it can
link to results from other runs, as just mentioned.
As implemented, the
Javadoc tool requires and relies on the java compiler
to do its job. The
Javadoc tool calls part of
javac to compile the
declarations, ignoring the member implementation.
It builds a rich
internal representation of the classes, including the class
hierarchy, and "use" relationships, then generates the HTML from
that. The
Javadoc tool also picks up user-supplied documentation from
documentation comments in the source code.
In fact, the
Javadoc tool will run on
.java source files that are pure stub
files with no method bodies.
This means you can write
documentation comments and run the
Javadoc tool in the earliest stages of
design while creating the API, before writing the implementation.
Relying on the compiler ensures that the HTML output
corresponds
exactly with the actual implementation, which may rely on
implicit, rather than explicit, source code.
For example, the
Javadoc tool will document default constructors (section 8.6.7 of Java Language
Specification) that are present in the
.class files but not in the
source code.
In many cases, the
Javadoc tool allows you to generate documentation from source files whose
code is incomplete or erroneous. This is a benefit that enables you
to generate documentation before all debugging and troubleshooting
is done. For example, according to the Java Language Specification,
a class that contains an abstract method should itself be
declared abstract. The
Javadoc tool does not check for this, and would proceed without a warning,
whereas the
javac compiler stops on this error. The
Javadoc tool does do some primitive checking of doc comments. Use the
DocCheck doclet to check the doc comments more thoroughly.
When the
Javadoc tool builds its internal structure for the
documentation,
it loads all referenced classes.
Because of this, the
Javadoc tool must be
able to find all referenced classes, whether bootstrap classes,
extensions, or user classes.
For more about this, see How
Classes Are Found.
Generally speaking, classes you create must either
be loaded as an extension or in
the
Javadoc tools class path.
javadoc Doclets
You can customize the content and format of
the
Javadoc tools output
by using doclets. The
Javadoc tool has a default "built-in" doclet, called
the standard doclet, that generates HTML-formatted API documentation.
You can modify or subclass the standard doclet, or write your
own doclet to generate HTML, XML, MIF, RTF or whatever output
format youd like.
Information about doclets and their use is at the
following locations:
Tag | Description |
o
|
Javadoc Doclets
|
o
|
The
-doclet command-line option
|
When a custom doclet is not specified with the
-doclet command line option, the
Javadoc tool uses the default standard doclet.
The
Javadoc tool has several command line options that are
available regardless of which doclet is being used.
The standard doclet
adds a supplementary set of command line options.
Both sets of
options are described below in the options section.
Related Documentation and Doclets
Tag | Description |
o
|
Javadoc Enhancements for details about improvements added in
Javadoc 1.4.
|
o
|
Javadoc FAQ for answers to common questions, information about
Javadoc-related tools and workarounds for bugs.
|
o
|
How to Write Doc Comments for Javadoc for more information
about Sun conventions for writing documentation comments.
|
o
|
Requirements for Writing API Specifications - Standard
requirements used when writing the Java 2 Platform Specification.
It can be useful whether you are writing API specifications in
source fiel documentation comments or in other formats.
It covers requirements for packages, classes, interfaces, fields
and methods to stisfy testable assertions.
|
o
|
Documentation Comments Specification - The original specification
on documentation comments, Chapter 18, Documentation Comments,
in the Java Language Specification, First Edition, by James Gosling,
Bill Joy and Guy Steele. (This chapter was removed from the second
edition.)
|
o
|
DocCheck Doclet - Check doc comments in source files and generates a
report listing the errors and irregularities it finds. It is part of
the Sun Doc Check Utilities.
|
o
|
MIF Doclet - Can automate the generation of API documentation in
MIF, FrameMaker and PDF formats. MIF is Adobe FrameMakers interchange
format.
|
Terminology
A few terms have specific meanings within the context of the
Javadoc tool:
Tag | Description |
generated document
| |
The document generated by the
javadoc tool from the doc
comments in Java source code.
The default generated document
is in HTML and is created by the standard doclet.
|
name
|
A name in the Java Language, namely the name of a package,
class, interface, field, constructor, or method.
A name can be
fully-qualified, such as
java.lang.String.equals(java.lang.Object), or partially-qualified, such as
equals(Object). |
documented classes
| |
The classes and interfaces for which full documentation is
generated during a
javadoc run. To be documented, the source
files must be available, and either their source filenames or
package names must be passed into the
javadoc command.
We also refer to these as the classes included in the
javadoc run, or the included classes.
|
inlcuded classes
| |
Classes and interfaces whose source filenames or package names are
passed into the
javadoc command.
|
excluded classes
| |
Classes and interfaces whose source filename or package names are
not passed into the
javadoc command.
|
referenced classes
| |
The classes and interfaces that are explicitly referred to in
the definition (implementation)
or doc comments of the documented classes and interfaces.
Examples of references include return type,
parameter type, cast type, extended class, implemented
interface, imported classes, classes used in method bodies,
@see, {@link}, {@linkplain}, and {@inheritDoc} tags.
(Notice this definition has changed since 1.3.)
tags) do not qualify as referenced classes.
When thE
Javadoc tool
is run, it should load into memory all of the referenced classes in
javadocs bootclasspath and classpath.
(The Javadoc tool prints a
"Class not found" warning for referenced classes not found.)
The
Javadoc tool can derive enough information from the
.class files to determine their existence and the fully qualified
names of their members.
|
external referenced classes
| |
The referenced classes whose documentation not being
generated during a
javadoc run.
In other words, these classes
are not passed into the
Javadoc tool on the comand line.
Links for names in the generated
documentation to those classes are said to be external
references or external links.
For example, if you run the
Javadoc tool on only the
java.awt package, then any class in
java.lang, such as Object, is an external referenced class.
External referenced classes can be linked to using the
-link and
-linkoffline options.
An important property of an external referenced class is that its
source comments are normally not available to the
Javadoc run. In this case, these comments cannot be inherited.
|
Source Files
The
Javadoc tool will generate output originating from four different types
of "source" files: Java language source files for
classes (.java), package
comment files, overview comment files, and miscellaneous
unprocessed files.
Class Source Code Files
Each class or interface and its members can have their own documentation
comment, contained in a
.java file.
For more details about these doc commments, see
Documentation Comments below.
Package Comment Files
Each package can have its own documentation comment, contained in its
own "source" file, that the
Javadoc tool will merge into the package
summary page that it generates.
You typically include in this
comment any documentation that applies to the entire package.
To create a package comment file, you must name it
package.html and place it in the package directory in the source tree along
with the
.java files. The
Javadoc tool will automatically look for this
filename in this location.
Notice that the filename is identical
for all packages. For explicit details,
see the example of package.html.
The content of the package comment file is one big documentation
comment, written in HTML, like all other comments, with one
exception: The documentation comment should not include the
comment separators /** and */ or leading asterisks.
When writing
the comment, you should make the first sentence a summary about
the package, and not put a title or any other text between
<body> and the first sentence.
You can include package tags; as with any
documentation comment, all tags except {@link} must appear after
the description.
If you add a
@see tag in a package comment
file, it must have a
fully qualified name.
When the
Javadoc tool runs, it automatically looks for this file; if found,
the
Javadoc tool does the following:
Tag | Description |
o
|
Copies all content between
<body> and
</body> tags for
processing.
|
o
|
Processes any package tags that are present.
|
o
|
Inserts the processed text at the bottom of the package
summary page it generates, as shown in Package Summary.
|
o
|
Copies the first sentence of the package comment to the top
of the package summary page.
It also adds the package name
and this first sentence to the list of packages on the
overview page, as shown in Overview Summary.
The end-of-sentence is determined by the same rules used for the
end of the first sentence of class and member descriptions.
|
Overview Comment File
Each application or set of packages that you are documenting can
have its own overview documentation comment, kept in its own
"source" file, that the
Javadoc tool will merge into the overview page that
it generates.
You typically include in this comment any
documentation that applies to the entire application or set of
packages.
To create an overview comment file, you can name the file anything
you want, typically
overview.html, and place it anywhere, typically
at the top level of the source tree.
Notice that you can have multiple
overview comment files for the same set of source files, in case
you want to run
javadoc multiple times on different sets of packages.
For example, if the source files for the
java.applet package are contained in
/home/user/src/java/applet directory, you
could create an overview comment file at
/home/user/src/overview.html.
The content of the overview comment file is one big documentation
comment, written in HTML, like the package comment file described
previously.
See that description for details.
To reiterate, when
writing the comment, you should make the first sentence a summary
about the application or set of packages, and not put a title or
any other text between
<body> and the first sentence.
You can
include overview tags; as with any documentation comment, all tags
except {@link} must appear after the description.
If you add a
@see tag, it must have a fully-qualified name.
When you run the
Javadoc tool,
you specify the overview comment file name with the
-overview option.
The file is then processed, similar to
that of a package comment file:
Tag | Description |
o
|
Copies all content between
<body> and
</body> tags for processing.
|
o
|
Processes any overview tags that are present.
|
o
|
Inserts the processed text at the bottom of the overview page
it generates, as shown in Overview Summary.
|
o
|
Copies the first sentence of the overview comment to the top
of the overview summary page.
|
Miscellaneous Unprocessed Files
You can also include in your source any miscellaneous files that
you want the
Javadoc tool to copy to the destination directory.
These typically include
graphic files (for example, Java source (.java) and
class (.class) files) and self-standing HTML files whose content
would overwhelm the documentation comment of a normal Java source
file.
To include unprocessed files, put them in a directory called
doc-files, which can be a subdirectory of any package directory.
You can have one such subdirectory for each package.
You might include images, example code, source files,
.class files, applets, and HTML files.
For example, if you want to include the image of a button
button.gif in the
java.awt.Button class documentation,
you place that file in the
/home/user/src/java/awt/doc-files/ directory.
Notice the
doc-files directory should not be located at
/home/user/src/java/doc-files because
java is not a package - that is, it does not
directly contain any source files.
All links to these unprocessed files must be
hard-coded, because the
Javadoc tool does not look at the files - it
simply copies the directory and all its contents to the
destination.
For example, the link in the
Button.java doc comment might look like:
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
|
Test Files and Template Files
Some developers have indicated they want
to store test files and templates files in the source
tree near their corresponding source files.
That is, they would like to put them in the same
directory, or a subdirectory, of those source files.
If you run the Javadoc tool by explicitly
passing in individual sourcefilenames, you can
deliberately omit test and templates files
andprevent them from being processed. However, if
you are passing in package names or wildcards,
you need to follow certain rulesto ensure these
test files and templates files are not processed.
Test files differ from template files in that
the former arelegal, compilable source files, while the
latter are not, but may end with ".java".
Tag | Description |
Test files - | |
Often developers want to put compilable,
runnable test files for a given package in
the same directory as the source files for that package.
But they want the test files to belong to a
package other than the source file package, such
as the unnamed package (so test files have no
package statement or a different package statement
from the source). In this scenario, when
the source is being documented by specifying
its package name specified on the command line, the test
files will cause warnings or errors. You need to
put such test files in a subdirectory. For example,
if you want to add test files for source files in
com.package1 put them in a subdirectory that would be an invalid package
name (because it contains a hyphen):
|
Tag | Description |
|
com/package1/test-files/
|
The test directory will be skipped by the Javadoc tool
with no warnings.
If your test files contain doc comments, you can
set up a separate run of the Javadoc tool to
produce documentation of the test files by passing in
their test source filenames with wildcards, such
as
com/package/ est-filesjava .
Tag | Description |
Tempaltes for source files -
| |
Template files have names that often
end in ".java" and are not
compilable. If you have a template for
a source file that you want to keep
in the source directory,
you can name it with a dash (such as Buffer-Template.java ),
or any other illegal Java character,
to prevent it from being processed. This relies on the
fact that the Javadoc tool will only process
sourcefiles whose name, when stripped of
the ".java" suffix, is actually a legal class name (see
Identifiers ).
|
Generated Files
By default,
javadoc uses a standard doclet that generates
HTML-formatted documentation.
This doclet generates the following
kinds of files (where each HTML "page" corresponds to a separate
file).
Note that
javadoc generates files with two types of names:
those named after classes/interfaces, and those that are not (such
as package-summary.html).
Files in the latter group contain
hyphens to prevent file name conflicts
with those in the former group.
Basic Content Pages
Tag | Description |
o
|
One class or interface page (classname.html) for each class
or interface it is documenting.
|
o
|
One package page (package-summary.html) for each package it
is documenting. The
Javadoc tool includes any HTML text provided
in a file named
package.html in the package directory of the
source tree.
|
o
|
One overview page (overview-summary.html) for the entire set
of packages.
This is the front page of the generated document.
The
Javadoc tool includes any HTML text provided in a
file specified with the
-overview option.
Note that
this file is created only if you pass into
javadoc two or more package
names.
For further explanation, see
HTML Frames below.
|
Cross-Reference Pages
Tag | Description |
o
|
One class hierarchy page for the entire set of packages
(overview-tree.html).
To view this, click on "Overview" in
the navigation bar, then click on "Tree".
|
o
|
One class hierarchy page for each package (package-tree.html).
To view this, go to a particular package, class or interface
page; click "Tree" to display the hierarchy for that package.
|
o
|
One "use" page for each package (package-use.html) and a
separate one for each class and interface
(class-use/classname.html). This page describes what
packages, classes, methods, constructors, and fields use any
part of the given class, interface, or package.
Given a class
or interface A, its "use" page includes subclasses of A,
fields declared as A, methods that return A, and methods and
constructors with parameters of type A.
You can access this
page by first going to the package, class, or interface, then
clicking on the "Use" link in the navigation bar.
|
o
|
A deprecated API page (deprecated-list.html) listing all
deprecated names.
(A deprecated name is not recommended for
use, generally due to improvements, and a replacement name is
usually given.
Deprecated APIs may be removed in future implementations.)
|
o
|
A constant field values page (constant-values.html) for
the values of static fields.
|
o
|
A serialized form page (serialized-form.html) for information
about serializable and externalizable classes.
Each such
class has a description of its serialization fields and
methods.
This information is of interest to re-implementors,
not to developers using the API.
While there is no link in
the navigation bar, you can get to this information by going
to any serialized class and clicking "Serialized Form" in the
"See also" section of the class description.
The standard doclet automatically generates a serialized form
page: any class (public or non-public) that implements
Serializable is included, along with
readObject and
writeObject methods, the fields that are serialized, and the doc
comments from the @serial, @serialField, and @serialData
tags. Public serializable classes can be excluded by marking them
(or their package) with @serial exclude, and package-private
serializable classes can be included by marking them
(or their package) with @serial include. As of 1.4, you can
generate the complete serialized form for public and private
classes by running javadoc without specifying the
-private option.
|
o
|
An index (index-*.html) of all class, interface, constructor,
field and method names, alphabetically arranged.
This is internationalized for Unicode and can be generated as a
single file or as a separate file for each starting character
(such as A-Z for English).
|
Support Files
Tag | Description |
o
|
A help page (help-doc.html) that describes the navigation bar
and the above pages.
You can provide your own custom help
file to override the default using
-helpfile. |
o
|
One
index.html file that creates the HTML frames for display.
This is the file you load to display the front page
with frames.
This file itself contains no text content.
|
o
|
Several frame files (*-frame.html) containing lists of
packages, classes and interfaces, used when HTML frames are
being displayed.
|
o
|
A package list file (package-list), used by the
-link and
-linkoffline options.
This is a text file, not HTML, and is
not reachable through any links.
|
o
|
A style sheet file (stylesheet.css) that controls a limited
amount of color, font family, font size, font style, and
positioning on the generated pages.
|
o
|
A doc-files directory that holds any image, example, source
code, or other files that you want copied to the destination
directory.
These files are not processed by the
Javadoc tool in any
manner, that is, any
javadoc tags in them will be ignored.
This directory is not generated unless it exists in the
source tree.
|
HTML Frames
The
Javadoc tool
will generate either two or three HTML frames, as shown in
the figure below.
When you pass source files (*.java) or a single
package name as arguments into the
javadoc command, it creates
only one frame (C) in the left-hand column, that is,
the list of classes.
When you pass into
javadoc two or more package names, it creates a
third frame (P) listing all packages, as well as an overview page
(Detail).
This overview page has the file name,
overview-summary.html. Thus, this file is created only if you pass
in two or more package names.
You can bypass frames by clicking on
the "No Frames" link or entering at
overview-summary.html.
If you are unfamiliar with HTML frames, you should be aware that
frames can have focus for printing and scrolling.
To give a frame
focus, click on it.
Then, on many browsers the arrow keys and page
keys will scroll that frame,
and the print menu command will print it.
------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt
|
Load one of the following two files as the starting page depending
on whether you want HTML frames or not:
Tag | Description |
o
|
index.html (for frames)
|
o
|
overview-summary.html (for no frames)
|
Generated File Structure
The generated class and interface files are organized in the same
directory hierarchy as Java source files and class files.
This structure is one directory per subpackage.
For example, the document generated for the class
java.applet.Applet would be located at
java/applet/Applet.html. The file structure for the
java.applet package follows, given that the destination directory is named
apidocs. All files that contain the word "frame" appear in the
upper-left or lower-left frames, as noted.
All other HTML files
appear in the right-hand frame.
NOTE: Directories are shown in bold.
The asterisks (*)
indicate the files and directories that are omitted when
the arguments to
javadoc are source file names (*.java)
rather than package names.
Also, when arguments are
source file names,
package-list is created but is empty.
The
doc-files directory is not created in the
destination unless it exists in the source tree.
apidocs | Top directory |
index.html | Initial page that sets up HTML frames |
* overview-summary.html | Lists all packages with first sentence summaries |
overview-tree.html | Lists class hierarchy for all packages |
deprecated-list.html | Lists deprecated API for all packages |
constant-values.html Lists values of static fields for all packages | |
serialized-form.html | Lists serialized form for all packages |
* overview-frame.html | Lists all packages, used in upper-left frame |
allclasses-frame.html | Lists all package classes, lower-left frame |
help-doc.html | Lists user help for how pages are organized |
index-all.html | Default index created w/o -splitindex option |
index-files | Directory created with -splitindex option |
index-<number>.html | Index files created with -splitindex option |
package-list | Lists package names used only for resolving external refs |
stylesheet.css | HTML style sheet for defining fonts, colors, positions |
java | Package directory |
applet | Subpackage directory |
Applet.html | Page for Applet class |
AppletContext.html | Page for AppletContext interface |
AppletStub.html | Page for AppletStub interface |
AudioClip.html | Page for AudioClip interface |
* package-summary.html | Lists classes with first sentence summaries |
* package-frame.html | Lists package classes, lower left-hand frame |
* package-tree.html | Lists class hierarchy for this package |
package-use | Lists where this package is used |
doc-files | Directory holding image & example files |
class-use | Directory holding pages API is used |
Applet.html | Page for uses of Applet class |
AppletContext.html | Page for uses of AppletContext interface |
AppletStub.html | Page for uses of AppletStub interface |
AudioClip.html | Page for uses of AudioClip interface |
src-html | Source code directory |
| java |
| |
| |
| |
| |
| |
Generated API Declarations
The
Javadoc tool generates a declaration at the start of each class, interface, field,
constructor, and method description. This declaration is the declaration for
that API item. For example, the declaration for the Boolean class is:
public final class Boolean
extends Object
implements Serializable
|
and the declaration for the Boolean.valueOf method is:
public static Boolean valueOf(String s)
|
The
Javadoc tool can include the modifiers
public, protected, private, abstract, final, static, transient, and
volatile, but not
synchronized or
native. These last two modifiers are considered implementation detail
and not part of the API specification.
Rather than relying on the keyword
synchronized, APIs should document their concurrency semantics in the
comment description, as in "a single
Enumeration cannot be used by multiple threads concurrently".
The document should not describe how to achieve these semantics. As
another example, while
Hashtable should be thread-safe, theres no reason to specify that we achieve
this by synchronizing all of its exported methods. We should reserve the
right to synchronize internally at the bucket level, thus offering
higher concurrency.
Documentation Comments
The original "Documentation Comments Specification" can be found
under related documentation.
Commenting the Source Code
You can include documentation comments ("doc comments")
in the source code, ahead
of declarations for any entity (classes, interfaces, methods,
constructors, or fields).
You can also create doc comments for each package and another
one for the overview, though their syntax is slightly different.
Doc comments are also known as Javadoc comments.
A doc comment consists of the characters between the
characters
/** that begin the comment and the characters
*/ that end it.
Leading asterisks are allowed on each line and are described
further below.
The text can continue onto multiple lines.
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
|
To save space you can put a comment on one line:
/** This comment takes up only one line. */
|
Placement of comments - Documentation comments are recognized only
when placed immediately before class, interface, constructor,
method, or field declarations (see the class example, method
example, and field example).
Documentation comments placed in the
body of a method are ignored.
Only one documentation comment per
declaration statement is recognized by the
Javadoc tool.
A common mistake is to put an import statement between the class
comment and the class declaration.
Avoid this, as
javadoc will ignore the class comment.
/**
* This is the class comment for the class Whatever.
*/
import com.sun; // MISTAKE - Important not to put statement here
public class Whatever {
}
|
A comment is a description followed by tags -
The description
begins after the starting delimiter
/** and continues until the tag section.
The tag section starts with the first character
@ that begins a line (ignoring leading asterisks and white space).
It is possible to have a comment with only tags and no description.
The description cannot continue after the tag section begins.
The argument to a tag can span multiple lines.
There can be any number of tags - some types of tags can be
repeated while others cannot.
This
@see starts the tag section:
/**
* This is a doc comment.
* @see java.lang.Object
*/
|
Standard and in-line tags -
A
tag is a special keyword within a doc comment that the Javadoc tool can process.
The Javadoc tool has standalone tags, which appear as
@tag, and in-line tags, which appear within braces, as
{@tag}. To be interpreted, a standalone tag must appear at the beginning of a line,
ignoring leading asterisks, white space and comment separator (/**).
This means you can use the @ character elsewhere in the text and it will
not be interpreted as the start of a tag. If you want to start a line with
the @ character and not have it be interpreted, use the HTML entity @.
Each standalone tag has associated text, which includes any text following the
tag up to, but not including, either the next tag, or the end of the doc
comment. This associated text can span multiple lines.
An in-line tag is allowed and interpreted anywhere that text is
allowed. The following example contains the standalone tag
@deprecated and in-line tag
{@link}.
/**
* @deprecated As of JDk 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
|
Comments are written in HTML -
The text must be written in HTML, in that they should
use HTML entities and HTML tags.
You can use whichever version of HTML your browser supports;
we have written the standard doclet to generate HTML 3.2-compliant code
elsewhere (outside of the documentation comments) with the
inclusion of cascading style sheets and frames.
(We preface each generated file
with "HTML 4.0" because of the frame sets.)
For example, entities for the less-than (<) and greater-than (>)
symbols should be written
< and
>. Likewise, the ampersand
(&) should be written
&. The bold HTML tag <b> is shown in the
following example:
/**
* This is a <b>doc</b> comment.
* @see java.lang.Object
*/
|
Leading asterisks -
When
javadoc parses a doc comment, leading
asterisk (*) characters on each line are discarded; blanks and
tabs preceding the initial asterisk (*) characters are also
discarded.
If you omit the leading asterisk on a line, all
leading white space is removed.
Therefore, you should not omit leading
asterisks if you want leading white space to be kept, such as when
indenting sample code with the
<pre> tag.
First sentence -
The first sentence of each doc comment should be a summary
sentence, containing a concise but complete description of the
declared entity.
This sentence ends at the first period that is
followed by a blank, tab, or line terminator, or at the first
standalone tag. The
Javadoc tool copies this first sentence to the member summary at the
top of the HTML page.
Declaration with multiple fields -
Java allows declaring multiple
fields in a single statement, but this statement can have only
one documentation comment, which is copied for all fields.
Therefore, if you want individual
documentation comments for each field,
you must declare each field in a separate statement.
For example, the
following documentation comment doesnt make sense when written as a
single declaration and would be better handled as two declarations:
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
|
The
Javadoc tool generates the following documentation from the above
code:
public int x
The horizontal and vertical distances of point
(x,y).
The horizontal and vertical distances of point
(x,y).
Use header tags carefully -
When writing documentation comments
for members, it is best not to use HTML heading tags such as
<H1> and
<H2>, because the
Javadoc tool creates an entire structured document
and these structural tags can interfere with the formatting
of the generated document.
However, it is fine to use these headings
in class and package comments to provide your own structure.
Automatic Reuse of Method Comments
The
Javadoc tool has the ability to automatically reuse or "inherit"
method comments in classes and interfaces. When a description,
or @return, @param, @see or @throws tag is missing from a
method comment, the
Javadoc tool instead copies the corresponding description or tag
comment from the method it overrides or implements (if any),
according to the algorithm below.
More specifically, when a @param tag for a particular parameter
is missing, then the comment for that parameter is copied.
When an @throws tag for a particular exception is missing,
the @throws tag is copied only if that exception is declared.
This behavior contrasts with version 1.3 and earlier, where
the presence of any description or tag would prevent all comments
from being inherited.
Also of interest, is the inline tag {@inheritDoc} is
present in a description or any tag, the corresponding description
or tag is copied at that spot.
The overridden method must be a member of a documented class, and
not an external referenced class for the doc comment to actually
be available to copy.
Inheriting of comments occurs in three cases:
Tag | Description |
o
|
When a method in a class overrides a method in a superclass
|
o
|
When a method in an interface overrides a method in a
superinterface
|
o
|
When a method in a class implements a method in an interface
|
In the first two cases, for method overrides, the
Javadoc tool generates a subheading "Overrides" in the
documentation for the overriding method,
with a link to the method it is overriding.
In the third case, when a method in a given class implements a
method in an interface, the
Javadoc tool generates a subheading
"Specified by" in the documentation for the overriding method,
with a link to the
method it is implementing.
Algorithm for Inheriting Method Descriptions
If a method does not have a doc comment, the
Javadoc tool searches for an applicable comment using the
following algorithm, which is designed to find the most
specific applicable doc comment, giving
preference to interfaces over superclasses:
Tag | Description |
1.
|
Look in each directly implemented (or extended) interface in
the order they appear following the word implements (or extends)
in the method declaration. Use the first doc comment found for this method.
|
2.
|
If step 1 failed to find a doc comment, recursively apply this entire
algorithm to each directly implemented (or extended)
interface, in the same order they were examined in step 1.
|
3. If step 2 failed to find a doc comment and this is
| |
a class other than Object (not an interface):
a. If the superclass has a doc comment for this method, use it.
b. If step 3a failed to find a doc comment, recursively apply this
entire algorithm to the superclass.
|
|
javadoc Tags
The
Javadoc tool parses special tags when they are embedded within a
Java doc comment.
These doc tags enable you to autogenerate a complete,
well-formatted API from your source code.
The tags start with an
"at" sign (@) and are case-sensitive -
they must be typed with
the uppercase and lowercase letters as shown.
A tag must start at
the beginning of a line (after any leading spaces and an optional
asterisk) or it is treated as normal text.
By convention, tags with the same name are grouped together.
For example, put all
@see tags together.
Tags come in two types:
o
Standalone tags - Can be placed only in the tag section that
follows the desription. There tags are not set off with
curly braces: @tag.
o
Inline tags - Can be placed anywhere in the comments description
or in the comments for standalone tags. Inline tags are set off
with curly braces:{@tag}.
For information about tags we might introduce in future releases,
see Proposed Tags.
The current tags are:
Tag | Introduced |
| in JDK |
@author | 1.0 |
{@code} | 1.5 |
{@docRoot} | 1.3 |
@deprecated | 1.0 |
@exception | 1.0 |
{@inheritDoc} | 1.4 |
{@link} | 1.2 |
{@linkplain} | 1.4 |
{@literal} | 1.5 |
@param | 1.0 |
@return | 1.0 |
@see | 1.0 |
@serial | 1.2 |
@serialData | 1.2 |
@serialField | 1.2 |
@since | 1.1 |
@throws | 1.2 |
{@value} | 1.4 |
@version | 1.0 |
For custom tags, see the -tag option.
Tag | Description |
@author name-text | |
Adds an "Author" entry with the specified name-text to the
generated docs when the
-author option is used.
A doc comment may contain multiple
@author tags.
You can specify one name per
@author tag or multiple names per tag.
In the former case, the
Javadoc tool inserts a comma (,) and space between names.
In the latter case, the entire text is simply copied to the
generated document without being parsed.
Therefore, use
multiple names per line if you want a localized name
separator other than a comma.
|
Tag | Description |
@deprecated deprecated-text | |
Adds a comment indicating that this API should no longer be
used (even though it might continue to work).
javadoc moves the
deprecated-text ahead of the description, placing it in
italics and preceding it with a bold warning: "Deprecated".
|
Tag | Description |
|
The first sentence of deprecated-text should at least tell
the user when the API was deprecated and what to use as a
replacement.
javadoc copies just the first sentence to the
summary section and index.
Subsequent sentences can also
explain why it has been deprecated.
You should include a
{@link} tag (for
javadoc 1.2 or later) that points to the
replacement API:
Tag | Description |
o
|
For
javadoc 1.2, use a {@link} tag. This creates the
link in-line, where you want it. For example:
Tag | Description |
|
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
|
|
|
o
|
For
javadoc 1.1, the standard format is to create a
@see tag (which cannot be in-line) for each
@deprecated tag.
|
For more about deprecation, see the
@deprecated tag.
|
{@code text} | |
Equivalent to <code>{@literal}</code> .
|
Displays text in code font without
interpreting the text as HTML markup or
nested javadoc tags. This enables you to
use regular angle brackets ( < and > )
instead of the HTML entities ( < and > )
in doc comments, such as in
parameter types ( <Object> ),
inequalities ( 3 < 4 ), or arrows ( <- ). For example,
the doc comment text:
{@code A<B>C}
displays in the generated HTML page unchanged as:
A<B>C
The noteworthy point is that the <B> is not
interpreted as boldand is in code font.
If you want the same functionality without the
code font, use {@literal}.
Tag | Description |
{@docRoot} | |
Represents the relative path to the generated documents
(destination) root directory from any generated page.
It is useful when you want to include a file, such as a
copyright page or company logo, that you want to
reference from all generated pages.
Linking to the copyright page from the bottom of each page is common.
This
{@docRoot} tag can be used both on the command line
and in a doc comment:
Tag | Description |
1.
|
On the command line, where the header/footer/bottom
are defined:
javadoc -bottom <a href= {@docRoot}/copyright.html >Copyright</a> |
NOTE - When using {@docRoot} this way in a make file,
some makefile programs require special escaping for the brace {}
characters. For example, the Inprise MAKE version 5.2 running
on Windows requires double braces: {{@docRoot}}. It also
requires double (rather than single) quotes to enclose
arguments to options such as -bottom (with the
quotes around the href argument omitted).
Tag | Description |
2.
|
In a doc comment:
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
|
|
The reason this tag is needed
is because the generated docs
are in hierarchical directories, as deep as the number of
subpackages.
This expression:
<a href= {@docRoot}/copyright.html >
would resolve to:
<a href="../../copyright.html"> ... for java/lang/Object.java
and
<a href="../../../copyright.html"> ... for java/lang/ref/Reference.java
|
@exception class-name description | |
The
@exception tag is a synonym for
@throws. |
{@inheritDoc}
| |
Inherits documentation from the nearest superclass into
the current doc comment. This allows comments to be abstracted
up the inheritance tree, and enables developers to write around
the copied text. Also see inheriting comments.
|
This tag can be places in two positions:
|
o
|
In the comment body (before the first standalone tag),
where it will copy the entire comment body from its superclass.
|
o
|
In the text argument of a standalone tag, where it
will copy the text of the tag from its superclass.
|
{@link " package.class#member label" }
| |
Inserts an in-line link with visible text
label that points to the documentation for the specified package, class or
member name of a referenced class.
This tag is very similar to
@see - both require the same references and accept exactly the same syntax
for package.class#member and
label. The main difference is that {@link} generates an in-line link rather than
placing the link in the "See Also" section. Also, the {@link} tag
begins and ends with curly braces to separate it from the rest of the
in-line text. If you need to use "}" inside the label, use the HTML
entity notation
}
There is no limit to the number of {@link} tags allowed in a
sentence.
You can use this tag in the description part of a
documentation comment or in the text portion of any tag (such
as
@deprecated, @return, or
@param).
For example, here is a comment that refers to the
getComponentAt(int, int) method:
Use the {@link #getComponentAt(int, int) getComponentAt} method.
|
>From this, the standard doclet would generate the following
HTML (assuming it refers to another class in the same
package):
Use the
<a href="Component.html#getComponentAt(int, int)">\
getComponentAt</a>method.
|
which appears on the web page as:
Use the getComponentAt method.
|
You can extend {@link} to link to classes not being documented
by using the
-link otion.
|
{@linkplain " package.class#member label"}
| |
Indentical to {@link}, except the links label is displayed
in plain text than code font. Useful when the label is plain text.
Example:
|
Refer to {@linkplain add() the overridden method}.
|
|
This would display as
|
Refer to the overridden method.
|
|
{@literaltext} | |
Displays text without interpreting the
text as HTML markup or nested javadoc
tags. This enables you to use regular angle
brackets ( < and > ) instead of the
HTML entities ( < and > ) in doc comments,
such as in parameter types ( <Object> ),
inequalities ( 3 < 4 ), or arrows ( <- ).
For example, the doc comment text:
|
Tag | Description |
|
{@literal A<B>C}
|
displays unchanged in the generated HTML page
in your browser, as:
|
|
A<B>C
|
The noteworthy point is that the <B> is not
interpreted as bold(and it is not in code font).
If you want the same functionality but with
the text in code font, use {@code} .
Tag | Description |
@param parameter-name description | |
Adds a parameter with the specified
parameter-name followed by the specified
description to the "Parameters" section.
When writing the doc comment, you may
continue the description onto multiple lines.
This tag is valid only in a doc comment
for a method, constructor or class.
|
The parameter-name can be the name of a
parameter in a method or constructor,
or the name of a type parameter of a
class. Use angle brackets around this
parametername to specify the use of
a type parameter, such as:
,nf
/**
* @param <E> Type of element stored in a list
*/
public interface List<E> extends Collection<E> {
}
For more details, see writing @param tags.
Tag | Description |
@return description | |
Adds a "Returns" section with the description text.
This text
should describe the return type and permissible range of values.
|
@see<ahref=URL#value>label</a> | |
Adds a link as defined by URL#value. The URL#value
is a relative or absolute URL. The Javadoc tool
distinguishes this from other cases by looking
for a less-than symbol (<) as the first character.
For example:
|
Tag | Description |
|
@see <a href="spec.html#section">Java Spec</a>
|
This generated a link such as:
|
|
See Also: "Java Spec"
|
@see string | |
Adds a text entry for string. No link is generated.
The string is a book or other reference to information not
available by URL. The
Javadoc tool distinguishes this from the
previous cases by looking for a double-quote (") as the
first character.
For example:
Tag | Description |
|
@see "The Java Programming Language"
|
This generates text such as:
See Also:
"The Java Programming Language"
|
|
|
@see <a href="URL#value">label</a>
| |
Adds a link as defined by
URL#value. The
URL#value is a relative or absolute URL. The
Javadoc tool distinguishes this
from other cases by looking for a less-than symbol (<)
as the first character.
For example:
Tag | Description |
|
@see <a href="spec.html#section">Java Spec</a>
|
This generates a link such as:
|
|
@see package.class#member label | |
Adds a link, with visible text label, that points to the
documentation for the specified name in the Java Language
that is referenced.
The label is optional; if omitted, the name
appears instead as the visible text, suitably shortened
(see How a Name Is Displayed).
Use the label when you want the
visible text to be abbreviated or different from the name.
Tag | Description |
|
In version 1.2, just the name but not the label would
automatically appear in
<code> HTML tags.
Starting with
1.2.2, the
<code> is always included around the visible
text, whether or not a label is used.
Tag | Description |
o
|
package.class#member is any valid name in the Java
Language that is referenced (package, class,
interface, constructor, method, or field name),
except that you replace the dot ahead of the member
name with a hash character (#).
If this name is in
the documented classes, the
Javadoc tool will automatically
create a link to it.
To create links to external
referenced classes, use the
-link option.
Use
either of the other two
@see forms for referring to
documentation of a name that does not belong to a
referenced class.
This argument is described
at greater length below under Specifying a Name.
|
o
|
label is optional text that is visible as the
links label.
The label can contain white space.
If a label is omitted, then
package.class.member will appear, suitably shortened relative to the current
class and package (see How a Name Is Displayed).
|
o
|
A space is the delimiter between
package.class#member and
label. A space inside
parentheses does not indicate the start of a label,
so spaces can be used between parameters in a method.
|
Example - In this example, an
@see tag (in the Character
class) refers to the equals method in the String class.
The tag includes both arguments, that is, the name
"String#equals(Object)" and the label "equals":
|
/**
* @see String#equals(Object) equals
*/
|
|
The standard doclet produces HTML something like this:
|
<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#equals\
(java.lang.Object)"><code>equals</code></a>
</dl>
|
|
The above looks something like this in a browser, where the
label is the visible link text:
|
|
Specifying a Name - This
package.class#member name can
be either fully qualified, such as
java.lang.String#toUpperCase(), or not, such as
String#toUpperCase() or
#toUpperCase(). If less than fully-qualified, the
Javadoc tool uses the normal Java compiler
search order to find it, further described below in
Search order for
@see. The name can contain whitespace
within parentheses, such as between method arguments.
|
Of course the advantage to providing shorter,
"partially-qualified" names is that they are less
to type and less clutter in the source code.
The following
table shows the different forms of the name, where Class
can be a class or interface, Type can be a class,
interface, array, or primitive, and method can be a
method or constructor.
|
Typical forms for
|
Referencing a member of the current class |
@see #field |
@see #method(Type, Type,...) |
@see #method(Type argname, Type argname,...) |
Referencing another class in the current or imported |
packages |
@see Class#field |
@see Class#method(Type, Type,...) |
@see Class#method(Type argname, Type argname,...) |
@see Class |
Referencing another package (fully qualified) |
@see package.Class#field |
@see package.Class#method(Type, Type,...) |
@see package.Class#method(Type argname, Type argname,...) |
@see package.Class |
@see package |
|
The following notes apply to the above table:
|
o
|
The first set of forms (with no class or package)
will cause the
Javadoc tool to search only through the
current classs hierarchy.
It will find a member of
the current class or interface, one of its
superclasses or superinterfaces, or one of its
enclosing classes or interfaces (search steps 1-3).
It will not search the rest of the current package
or other packages (search steps 4-5).
|
o
|
If any method or constructor is entered as a name
with no parentheses, such as getValue, and if
no field with the same name exists, the
Javadoc tool will correctly create a link to it, but will print a
warning message reminding you to add the
parentheses and arguments.
If this method is overloaded, the
Javadoc tool links to the first method
that its search encounters, which is unspecified.
|
o
|
Nested classes must be specified as
outer.inner, not only
inner, for all forms.
|
o
|
As stated, the hash character (#), rather than a
dot (.), separates a member from its class.
This enables the
Javadoc tool to resolve ambiguities, since the
dot also separates classes, nested classes,
packages, and subpackages.
However, the
Javadoc tool is generally lenient and will properly
parse a dot if you know there is no ambiguity, though it will
print a warning.
|
Search Order for @see: The
Javadoc tool will process an
@see tag that appears in a source file (.java), package file
(package.html), or overview file (overview.html).
In the latter two files, you must fully qualify the name you
supply with
@see. In a source file, you can specify a
name that is fully qualified or partially qualified.
When the
Javadoc tool encounters an
@see tag in a
.java file that
is not fully qualified, it searches for the specified
name in the same order as the Java compiler would
(except the
Javadoc tool will not detect certain namespace
ambiguities, since it assumes the source code is free of
these errors).
This search order is formally defined in
Chapter 6, "Names" of the
Java Language Specification, Second Edition. The
Javadoc tool searches for that name through all related and imported
classes and packages.
In particular, it searches in this order:
Tag | Description |
1.
|
The current class or interface
|
2.
|
Any enclosing classes and interfaces, searching
closest first
|
3.
|
Any superclasses and superinterfaces, searching
closest first
|
4.
|
The current package
|
5.
|
Any imported packages, classes and interfaces,
searching in the order of the import statement
|
The
Javadoc tool continues to search recursively through steps
1-3 for each class it encounters until it finds a match.
That is, after it searches through the current class and
its enclosing class E, it searches through Es
superclasses before Es enclosing classes.
In steps 4 and 5, the
Javadoc tool does not search classes or interfaces
within a package in any specified order (that order
depends on the particular compiler).
In step 5, the
Javadoc tool will look in
java.lang,sincethatisautomatically imported by all programs.
The
Javadoc tool wont necessarily look in subclasses, nor will
it look in other packages even if their documentation is
being generated in the same run.
For example, if the
@see tag is in
java.awt.event.KeyEvent class and refers
to a name in the
java.awt package,
javadoc will not look
in that package unless that class imports it.
How a Name is Displayed - If
label is omitted, then
package.class.member will appear.
In general, it will be
suitably shortened relative to the current class and
package.
By "shortened", we mean the
Javadoc tool will display
only the minimum name necessary.
For example, if the
String.toUpperCase() method contains references to a
member of the same class and to a member of a different
class, the class name will be displayed only in the
latter case:
Type
of
Ref-
erence
| Example | Displays As |
@see tag
refers
to
member
of
the
same
class
| @see
String#toLowerCase()
| toLowerCase()
(omits the class name)
|
@see
tag
refers
to
member
of a
differ-
ent
class
| @see
Character#toLowerCase(char)
| Character.toLowerCase(char)
(includes the class name)
|
Examples of @see: The comment to the right shows how the name would be
displayed if the
@see tag is in a class in another package,
such as
java.applet.Applet:
Example | See also: |
@see java.lang.String | // String |
@see java.lang.String The String class | // The String class |
@see String | // String |
@see String#equals(Object) | // String.equals(Object) |
@see String#equals | // String.equals\
(java.lang.Object)
|
@see java.lang.Object#wait(long) | // java.lang.Object.\
wait(long)
|
@see Character#MAX_RADIX | // Character.MAX_RADIX |
@see <a href="spec.html">Java Spec</a> | // Java Spec |
@see "The Java Programming Language" | // "The Java Programming \
Language"
|
|
|
You can extend @see to link to classes not being documented
| |
by using the
-link option.
|
@since since-text | |
Adds a "Since" heading with the specified
since-text to the generated documentation.
The text has no special internal structure.
This tag means that this change or feature has
existed since the software release specified by the
since-text. For example:
|
For source code in the Java platform, this tag indicated the
version of the Java platform API specification (not necessarily
when it was added to the reference implementation).
Tag | Description |
@serial field-description|include|exclude | |
Used in the doc comment for a default serializable field.
An optional
field-description augments the doc comment for the field.
The combined description must explain the meaning
of the field and list the acceptable values.
If needed, the
description can span multiple lines.
The standard doclet adds this information to the
serialized form page.
The
include and
exclude arguments identify whether a class or package should be included or
excluded from the serialized form page. They work as follows:
Tag | Description |
o A public or protected class that implements
| |
Serializable is
included unless the class (or its package) is marked
@serial exclude. |
o A private or package-private class that implements
| |
Serializable is
excluded unless that class (or its package) is marked
@serial include. |
Examples: The
javax.swing package is marked
@serial exclude (in package.html). The public class
java.sercurity.BasicPermission is marked
@serial exclude. The package-private class
java.util.PropertyPermissionCollection is marked
@serial include.
The tag
@serial at a class level overrides
@serial at a package level.
For more information about how to use these tags, along with
an example, see "Documenting Serializable Fields and Data for
a Class," Section 1.6 of the
Java Object Serialization Specification. Also see the "Serialization FAQ," which covers
the questions, "Why do I see
javadoc warnings stating that I am
missing
@serial tags? for private fields if I
am not running
javadoc with the -private switch?"
|
@serialField field-name field-type field-description | |
Documents an ObjectStreamField component of a Serializable
classs serialPersistentFields member.
One
@serialField tag
should be used for each ObjectStreamField component.
|
@serialData data-description | |
The
data-description documents the types and order of data in the serialized form.
Specifically, this data includes the optional data written by the writeObject
method and all data (including base classes) written by the
Externalizable.writeExternal method.
The
@serialData tag can be used in the doc comment for the
writeObject, readObject, writeExternal, and readExternal
methods.
|
@throws class-name description | |
The
@throws and
@exception tags are synonyms.
Adds a "Throws"
subheading to the generated documentation, with the
class-name and
description text.
The
class-name is the name
of the exception that may be thrown by the method.
If this
class is not fully specified, the
Javadoc tool uses the search order
to look up this class.
Multiple @throws tags can beused
in a given doc comment for
the same or different exceptions.
|
To ensure that all checked exceptions are
documented, if a @throws tag does not exist for an
exception inthe throws clause, the Javadoc
tool automatically adds that exception to the HTML
output (with no description) as if
it were documented with @throws tag.
|
The @throws documentation is copied from
an overridden method to a subclass only when the
exception is explicitly declared in the
overridden method. The same is true for copying from an
interfacemethod to an implementing method.
You can use {@inheritDoc} to force@throws to
inherit documentation.
|
For more details, see Writing @throws tags.
|
{@value package.class#field} | |
When {@value} is used (without any argument) in
the doc command of a static field, it displays the
value of that constant:
|
Tag | Description |
|
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
|
|
When used with argument
package.class#field in any doc comment, it displays
the value of the specified constant:
|
|
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {
}
|
|
The argument package.class#field takes a form
identical to that of the @see argument, except
that the member must be a static field.
These values of these constants are also displayed on the
Constant Field Values page.
Tag | Description |
@version version-text | |
Adds a "Version" subheading with the specified
version-text to the generated docs when the
-version option is used.
The text has no special internal structure.
A doc comment may
contain at most one
@version tag.
Version normally refers to
the version of the software (such as the Java 2 SDK) that contains
this class or member.
|
Where Tags Can Be Used
The following sections describe where the tags can be used.
Notice that these four tags can be used in all doc comments:
@see, @link, @since, @deprecated. Overview Documentation Tags
Overview tags are tags that can appear in the documentation
comment for the overview page, which resides in the source file
typically named (overview.html).
Like any other documentation
comments, these tags must appear after the description.
NOTE: The {@link} tag has a bug in overview documents in version 1.2.
Text appears properly but has no link. The {@docRoot} tag
foes not currently work in overview documents.
Overview Tags |
@see |
@since |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
Package Documentation Tags
Package tags are tags that can appear in the documentation comment
for a package (which resides in the source file
named package.html). The @serial tag can only be
used here with the include or exclude argument.
Package Tags |
@see |
@since |
@deprecated |
@serial |
@author |
{@link} |
{@linkplain} |
{@docRoot} |
Class and Interface Documentation Tags
The following are tags that can appear in the documentation
comment for a class or interface. The @serial tag can
only be used here with the include or exclude argument.
Class/Interface Tags |
@see |
@since |
@deprecated |
@serial |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
An example of a class comment:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.8, 06/24/04
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
}
|
Field Documentation Tags
The following are the tags that can appear in the documentation
comment for a field.
Field Tags |
@see |
@since |
@deprecated |
@serial |
@serialField |
{@link} |
{@linkplain} |
{@docRoot} |
{@value} |
An example of a field comment:
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
|
Constructor and Method Documentation Tags
The following are the tags that can appear in the documentation
comment for a constructor or method, except for {@inheritDoc},
which cannot appear in a constructor.
Method/Constructor Tags |
@see |
@since |
@deprecated |
@param |
@return |
@throws and @exception |
@serialData |
{@link} |
{@linkplain} |
{@inheritDoc} |
{@docRoot} |
An example of a method doc comment:
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
}
|
OPTIONS
The
Javadoc tool uses doclets to determine its output.
The
Javadoc tool
uses the default standard doclet unless a custom doclet is
specified with the
-doclet option.
The
Javadoc tool
provides a set of
command-line options that can be used with any doclet.
These options are described below under the sub-heading
Javadoc Options.
The standard doclet provides an additional set of command-line
options that are described below, under the sub-heading Options
Provided by the Standard Doclet.
All option names are
case-insensitive, though their arguments can be case-sensitive.
The options are:
-1.1 | -header | -package |
-author | -help | -private |
-bootclasspath | -helpfile | -protected |
-bottom | -J | -public |
-keywords | | |
-charset | -link | -quiet |
-classpath | -linkoffline | -serialwarn |
-d | -linksource | -source |
-docencoding | -locale | -sourcepath |
-doclet | -nodeprecated | -splitindex |
-docletpath | -nodeprecatedlist | -stylesheetfile |
-doctitle | -nohelp | -subpackages |
-encoding | -noindex | -tag |
-exclude | -nonavbar | -taglet |
-excludedocfilessubdir | -noqualifier | -tagletpath |
-extdirs | -nosince | -title |
-footer | -notree | -use |
-group | | -overview |
| | |
| | |
| | |
Javadoc Options
Tag | Description |
-overview path/filename | |
Specifies that
javadoc should retrieve the text for the
overview documentation from the "source" file specified by
path/filename and place it on the Overview page
(overview-summary.html).
The
path/filename is relative to the
-sourcepath.
While you can use any name you want for
filename and place it
anywhere you want for
path, a typical thing to do is to name it
overview.html and place it in the source tree at the
directory that contains the topmost package directories.
In this location, no path is needed when documenting packages,
since
-sourcepath will point to this file.
For example, if
the source tree for the
java.lang package is
/src/classes/java/lang/, then you could place the overview
file at
/src/classes/overview.html. See Real World Example.
For information about the file specified by
path/filename, see overview comment file.
Notice that the overview page is created only if you pass into
javadoc two or more package names.
For further explanation,
see HTML Frames.
The title on the overview page is set by
-doctitle . |
-public |
Shows only public classes and members.
|
-protected | |
Shows only protected and public classes and members.
This is the default.
|
-package |
Shows only package, protected, and public classes and
members.
|
-private |
Shows all classes and members.
|
-help |
Displays the online help, which lists these
javadoc and doclet command line options.
|
-doclet class | |
Specifies the class file that starts the doclet used in
generating the documentation.
Use the fully-qualified name.
This doclet defines the content
and formats the output.
If the
-doclet option is not used,
javadoc uses the standard doclet for generating the default
HTML format.
This class must contain the start(Root) method.
The path to this starting class is defined by the
-docletpath option.
|
For example, to call the MIF doclet, use:
|
|
-doclet com.sun.tools.doclets.mif.MIFDoclet
|
|
-docletpath classpathlist | |
Specifies the path to the doclet class file (specified
with the
-doclet option) and any jar files it depends on.
If the starting class file is in a jar file,
then this specifies the path to that jar
file, as shown in the example below.
You can specify an absolute path or
a path relative to the current directory.
If
classpath contains multiple paths or jar files,
they should be separated with a colon (:)
on Windows.
This option is not necessary if the
doclet is already in the search path.
|
Example of path to jar file that contains the
startig doclet class file. Notice the jar
filename is included.
|
|
-docletpath /home/user/mifdoclet/lib/mifdoclet.jar
|
|
Example of path to starting doclet class file. Notice the
class filename is omitted.
|
|
-docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
|
|
-1.1 |
This feature has been removed from Javadoc 1.4. There is no replacement for it.
This option created documentation with the appearance and functionality
of documentation generated by Javadoc 1.1 (including never supporting nested
classes). If you need this option, use Javadoc 1.2 or 1.3 instead.
|
-sourcepath sourcepathlist | |
Specifies the search paths for finding source files (.java)
when passing package names or -subpackages into the
javadoc command.
The
sourcepathlist can contain multiple paths by separating them with a
colon (:). The
Javadoc tool will search in all subdirectories of the specified paths.
Note that this option is not only used to located the
source files being documented, but also to find source
files that are not being documented but whose comments
are inherited by the source files being documented.
|
Note that you can use the
-sourcepath option only when passing
package names into the
javadoc command - it will not locate
.java files passed into the
javadoc command.
(To locate
.java files, cd to that directory or include the path ahead of each
file, as shown at Documenting One or More Classes.) If
-sourcepath is omitted,
javadoc uses the class path to find
the source files (see
-classpath). Therefore, the default
-sourcepath is the value of class path.
If
-classpath is omitted and you are passing package names into
javadoc, it looks in the current directory (and subdirectories) for the
source files.
|
|
Set
sourcepathlist to the root directory of the source tree
for the package you are documenting.
For example, suppose you
want to document a package called
com.mypackage whose source
files are located at:
Tag | Description |
|
/home/user/src/com/mypackage/*.java
|
|
In this case, you would specify the source path to
/home/user/src, the directory that contains
com/mypackage, and then supply the package name
com.mypackage:
Tag | Description |
|
example% javadoc -sourcepath /home/user/src/ com.mypackage
|
|
This is easy to remember by noticing that if you concatenate
the value of the source path and the package name together and
change the dot to a slash "/", you end up with the full path
to the package:
Tag | Description |
|
/home/user/src/com/mypackage
|
To point to two source paths:
Tag | Description |
|
example% javadoc -sourcepath /home/user/src/:/home/user2/src com.mypackage
|
|
|
-classpath classpathlist | |
Specifies the paths where
javadoc looks for referenced
classes (.class files) - these are the documented classes plus any
classes referenced by those classes.
The
classpathlist can contain multiple paths by separating them with a colon (:).
The
Javadoc tool will search in
all subdirectories of the specified paths.
Follow the instructions in class path documentation for
specifying
classpathlist.
If
-sourcepath is omitted, the
Javadoc tool uses
-classpath to find
the source files as well as class files (for backward
compatibility).
Therefore, if you want to search for source
and class files in separate paths, use both
-sourcepath and
-classpath.
For example, if you want to document
com.mypackage, whose source files reside in the directory
/home/user/src/com/mypackage, and if this package relies on a library in
/home/user/lib, you would specify:
Tag | Description |
|
example% javadoc -classpath /home/user/lib -sourcepath \
/home/user/src com.mypackage
|
|
As with other tools, if you do not specify
-classpath, the
Javadoc tool uses the CLASSPATH environment variable, if it is set.
If both are not set, the
Javadoc tool searches for classes from
the current directory.
For an in-depth description of how the
Javadoc tool uses
-classpath to find user classes as it relates to extension classes and
bootstrap classes, see How Classes Are Found.
|
-bootclasspath classpathlist | |
Specifies the paths where the boot classes reside.
These are
nominally the Java platform classes.
The
bootclasspath is part of
the search path the
Javadoc tool will use to look up source and class
files.
See How Classes Are Found for more details.
Separate directories in
classpathlist with colons (:).
|
-extdirs dirlist | |
Specifies the directories where extension classes reside.
These are any classes that use the Java Extension mechanism.
The
extdirs is part of the search path the
Javadoc tool will use to
look up source and class files.
See
-classpath (above) for
more details.
Separate directories in
dirlist with colons (:).
|
-verbose |
Provides more detailed messages while
javadoc is running.
Without the verbose option, messages appear for loading the
source files, generating the documentation (one message per
source file), and sorting.
The verbose option causes the
printing of additional messages specifying the number of
milliseconds to parse each java source file.
|
-quiet |
Shuts off non-error and non-warning messages, leaving
only the warnings and errors appear, making them easier
to view. Also suppresses the version string.
|
-locale language_country_variant | |
Important: The -locale option must be placed ahead (to the left) of any options provided by the standard doclet or any
other doclet. Otherwise, the navigation bars will appear in English.
This is the only command-line option that is order-dependent.
Specifies the locale that
javadoc uses when generating
documentation.
The argument is the name of the locale, as
described in java.util.Locale documentation, such as en_US
(English, United States) or en_US_WIN (Windows variant).
Specifying a locale causes
javadoc to choose the resource
files of that locale for messages (strings in the navigation
bar, headings for lists and tables, help file contents,
comments in
stylesheet.css, and so forth).
It also specifies
the sorting order for lists sorted alphabetically, and the
sentence separator to determine the end of the first sentence.
It does not determine the locale of the doc comment
text specified in the source files of the documented classes.
|
-encoding name | |
Specifies the source file encoding name, such as EUCJIS/SJIS.
If this option is not specified, the platform default
converter is used.
|
-Jflag |
Passes flag directly to the runtime system java that runs
javadoc. Notice there must be no space between the J and the
flag.
For example, if you need to ensure that the system sets
aside 32 megabytes of memory in which to process the
generated documentation, then you would call the
-Xmx option of java as
follows:
example% javadoc -J-Xmx32m -J-Xms32m com.mypackage
|
|
To tell what version of javadoc you are using, call the
-version option of java:
|
|
example% javadoc -J-version
java version "1.2"
Classic VM (build JDK-1.2-V, green threads, sunwjit)
|
|
(The version number of the standard doclet appears in its
output stream.)
Options Provided by the Standard Doclet
Tag | Description |
-d directory | |
Specifies the destination directory where
javadoc saves the generated HTML files.
(The "d" means "destination.") Omitting
this option causes the files to be saved to the current directory.
The value
directory can be absolute or relative to
the current working directory.
As of 1.4, the destination directory is
automatically created when javadoc is run.
|
For example, the following
generates the documentation for the
com.mypackage package and
saves the results in the
/home/user/doc/ directory:
|
|
example% javadoc -d /home/user/doc com.mypackage
|
|
-use |
Includes one "Use" page for each documented class and
package.
The page describes what packages, classes, methods,
constructors, and fields use any API of the given class or package.
Given class C, things that use class C would include
subclasses of C, fields declared as C, methods that return C,
and methods and constructors with parameters of type C.
For example, look at what might appear on the "Use"
page for String.
The
getName() method in the
java.awt.Font class returns type String.
Therefore,
getName() uses String,
and you will find that method on the "Use" page for String.
Note that this documents only uses of the API, not the
implementation.
If a method uses String in its implementation
but does not take a string as an argument or return a string,
that is not considered a "use" of String.
You can access the generated "Use" page by first going to the
class or package, then clicking on the "Use" link in the
navigation bar.
|
-version |
Includes the
@version text in the generated docs.
This text is omitted by default.
To tell what version of the
Javadoc tool you are using, use the
|
-author |
Includes the
@author text in the generated docs.
|
-splitindex | |
Splits the index file into multiple files, alphabetically,
one file per letter, plus a file for any index entries that
start with non-alphabetical characters.
|
-windowtitle title | |
Specifies the title to be placed in the HTML
<title> tag.
This appears in the window title and in any browser bookmarks
(favorite places) that someone creates for this page.
This title should not contain any HTML tags, as the browser cannot
properly interpret them.
Any internal quotation marks
within
title might have to be escaped.
If
-windowtitle is omitted, the
Javadoc tool uses the value of
-doctitle for this option.
example% javadoc -windowtitle "Java 2 Platform" com.mypackage
|
|
-doctitle title | |
Specifies the title to be placed near the top of the overview
summary file.
The title is placed as a centered,
level-one heading directly beneath the upper navigation bar.
The
title may contain HTML tags and white space, though if it
does, it must be enclosed in quotes.
Any internal quotation
marks within
title may have to be escaped.
example% javadoc -doctitle "Java<sup><font size=
TM</font></sup>" com.mypackage
|
|
-title title | |
This option no longer exists.
It existed only in Beta versions of
Javadoc 1.2.
It has been renamed to
-doctitle. This option was renamed to make it clear that it defines
the document title rather than the window title.
|
-header header | |
Specifies the header text to be placed at the top of each
output file.
The header is placed to the right of the
upper navigation bar.
header may contain HTML tags and white
space, though if it does, it must be enclosed in quotes.
Any internal quotation marks within
header may have to be escaped.
|
-footer footer | |
Specifies the footer text to be placed at the bottom of each
output file.
The footer is placed to the right of the
lower navigation bar.
footer may contain HTML tags and white
space, though if it does, it must be enclosed in quotes.
Any internal quotation marks within
footer may have to be escaped.
|
-bottom text | |
Specifies the text to be placed at the bottom of each output file.
The text is placed at the bottom of the page,
below the lower navigation bar.
text may contain HTML
tags and white space, though if it does, it must be enclosed
in quotes.
Any internal quotation marks within
text may have
to be escaped.
|
-link extdocURL | |
Creates links to existing
javadoc-generated
documentation of external referenced classes.
It takes one argument.
|
o
|
extdocURL is the absolute or relative URL of the directory
containing the external javadoc-generated documentation you want
to link to. Examples are shown below. The package-list file must
be found in this directory (otherwise, use -linkoffline). The
Javadoc tool reads the package names from the package-list file and then
links to those packages at that URL. When the
Javadoc tool is run, the
extdocURL value is copied literally into the <A HREF> links
that are created. Therefore,
extdocURL must be the URL to the directory, not to a file.
|
You can use an absolute link for
extdocURL to enable your docs to link to a document on any website,
or can use a relative link to link only to a relative
location. If relative, the value you pass in should be the
relative path from the destination directory (specified
with -d) to the diretory containing the packages being linked to.
|
When specifying an absolute link you normally use an http: link.
However, if you want to link to a file system that has no web
server, you can use a file: link - however, do this only if everyone
wanting to access the generated documentation shares the same
file system.
|
|
You can specify multiple -link options in a given javadoc run
to link to multiple documents.
Choosing between -linkoffline and -link -
One or the other option is appropriate when linking to an
API document that is external to the current javadoc run.
Use -link:
o
when using a relative path to the external API document, or
o
when using an absolute URL to the external API document, if you
shell does not allow a program to open a connection to that URL for
reading.
Use -linkoffline:
o
when using an absolute URL to the external API document, if your shell
does not allow a program to open a connection to that URL for reading.
This can occur if you are behind a firewall and the document
you want to link to is on the other side.
Example using absolute links to the external docs -
Lets say you want to link to the java.lang, java.io and
other Java 2 Platform packages at http://java.sun.com/j2se/1.4/docs/api.
The following command generates documentation for the package
com.mypackage with links to the Java 2 Platform
packages. The generated documentation will contain links to
the Object class, for example in the class trees. (Other options,
such as -sourcepath and -d, are not shown.)
Example using relative links to the external docs -
Lets say you have two packages whose docs are generated
in different runs of the
Javadoc tool, and those docs are separated by a relative path.
In this example, the packages are com.apipackage, and API,
and com.spipackage, an SPI (Service Provide Interface).
YOu want the documentation to reside in docs/api/com/apipackage
and docs/spi/com/spipackage. Assuming the API package documentation
is already generated, and that docs is the current directory,
you would document the SPI package with links to the API
documentation by running:
Tag | Description |
|
% javadoc -d ./spi -link ../api com.spipackage
|
|
Notice the -link argument is relative to the destination
directory (docs/spi).
Details -
The -link option enables you to link to classes referenced
to by your code but not documented in the current javadoc run.
For these links to go to valid pages, you must know where those
HTML pages are located, and specify that location with
extdocURL . This allows, for instance, third party documentation to link to
java.* documentation on http://java.sun.com.
Omit the -link option for javadoc to create links only to
API within the documentation it is generating in the current run.
(Without the -link option, the
Javadoc tool does not create links to documentation for
external references, because it does not know if
or where that documentation exists.
This option can create links in several places in the
generated documentation.
Another use is for cross-links
between sets of packages: Execute
javadoc on one set of
packages, then run
javadoc again on another set of packages,
creating links both ways between both sets.
A third use is as
a "hack" to update docs: Execute
javadoc on a full set of
packages, then run
javadoc again on only the smaller set of
changed packages, so that the updated files can be inserted
back into the original set.
Bug Fix for Referenced Classes -
In 1.4 the following bug has been fixed:
Tag | Description |
|
Link bug in 1.2 and 1.3 - When @see or {@link}
references an excluded class and -link is used,
an <A HREF> hyperlink is created only if the class is referenced
with in an import statement or in a declaration. References
in the body of methods, alone are inadequate. A workaround
was to include an explicit (not wildcard) import
statement for the referenced class.
|
|
An see or {@link} reference with -link is now enough to
load the referenced class and enable a link to it. You can remove
any import statements you had added as workarounds, which we had
suggested you comment as follows:
Tag | Description |
|
import java.lang.SecurityManager; // workaround to force @see/@link\
hyperlink
|
|
Package List - The
-link option requires that a file named
package-list, which is generated by the
Javadoc tool,
exist at the URL
you specify with
-link. The
package-list file is a simple
text file that lists the names of packages documented at that
location.
In an earlier example, the
Javadoc tool looks for a file named
package-list at the given URL, reads in the package names
and then links to those packages at that URL.
For example, the package list for the Java Platform v1.4 API
is located at
and starts out as follows:
Tag | Description |
|
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
etc.
|
|
When
javadoc is run without the
-link option, when it encounters a name that belongs to an
external referenced class, it prints the name with no link.
However, when the
-link option is used, the
Javadoc tool searches the
package-list file at the specified
extdocURL location for that
package name.
If it finds the package name, it prefixes the
name with
extdocURL .
In order for there to be no broken links, all of the
documentation for the external references must exist at the
specified URLs. The
Javadoc tool does not check that these pages exist, only that the
package-list exists.
Multiple Links: - You can supply multiple-link options to
link to any number of external generated documents.
Javadoc 1.2 has a known bug that prevents you from
supplying more than one
-link command.
This was fixed in 1.2.2.
Specify a different link option for each external document to
link to:
Tag | Description |
|
example% javadoc -link extdocURL1 -link extdocURL2 ... \
-link extdocURLn com.mypackage
|
|
where
extdocURL1, extdocURL2, ... extdocURLn point respectively to
the roots of external documents, each of which contains a
file named
package-list.
Cross-links - Note that "bootstrapping" may be required when
cross-linking two or more documents that have not been previously
generated.
In other words, if
package-list does not
exist for either document, when you run the
Javadoc tool on the first
document, the
package-list does not yet exist for the second
document.
Therefore, to create the external links, you must
rree-generate the first document after generating the second
document.
In this case, the purpose of first generating a document is
to create its
package-list (or you can create it by hand
if you are certain of the package names).
Then generate the
second document with its external links. The
Javadoc tool prints a
warning if a needed external
package-list file does not exist.
html.
Tag | Description |
-linkoffline extdocURL packagelistLoc | |
This option is a varition of
-link; they both create links to javadoc-generated
documentation for external referenced classes.
Use the
-linkoffline option when linking to a document on the web when the
Javadoc tool itself is "offline" - that is, it cannot access
the document through a web connection.
|
More specifically, use
-linkoffline is the external documents
package-list file is not accessible or does not exist at the
extdocURL location but does exist at a different location,
which can be specified by
packageListLoc (typically local). Thus, is
extdocURL is accessible only on the World Wide Web,
-linkoffline removes the constraint that the
Javadoc tool have a web connection when generating the
documentation. Examples are given below.
|
The
-linkoffline option takes two arguments - the first for the
string to be embedded in the <a href> links, the
second telling it where to find
package-list:
|
|
Tag | Description |
o
|
extdocURL is the absolute or relative URL of the directory containing the
external javadoc-generated documentation you want to
link to.
If relative, the value should be the relative path from the
destination directory (specified with -d)
to the root of the packages being linked to.
For more details see
extdocURL in the
-link option.
|
o
|
packagelistLoc is the path or URL to the directory containing
the
package-list file for the external documentation.
This can be a URL (http: or file:) or
file path, and can be absolute or relative.
If relative, make it relative to the current directory
from where javadoc was run. Do not include the
package-list filename.
|
You can specify multiple
-linkoffline options in a given
javadoc run.
(Prior to
1.2.2, it could be specified only once.)
Example using absolute links to the external docs -
Lets say you want to
link to the
java.lang, java.io and other Java 2 Platform packages at
http://java.sun.com/j2se/1.4/docs/api, but your shell does not have web
access. You could open the
package-list file in a browser at
http://java.sun.com/j2se/1.4/docs/api/package-list, save it to a local
directory, and point to this local copy with the second argument,
packagelistLoc . In this example, the package list
file has been saved to the current directory "." .
The following command generates documentation for the package
com.mypackage with links to the Java 2 Platform packages. The generated
documentation will contain links to the Object class, for example, in the class
trees. (Other necessary options, such as -sourcepath, are not shown.)
Example using relative links to the external docs -
Its not very common to
use
-linkoffline with relative paths, for the simple reason that
-link usually
suffices. When using
-linkoffline, the package-list file is generally local, and
when using relative links, the file you are
linking to is also generally local. So it
is usually unnecessary to give a different path for the two arguments to
-linkoffline . When the two arguments are identical, you can use
-link . See the
-link relative example.
Manually Creating A package-list File -
If a
package-list file does not yet
exist, but you know what package names your document will link to, you can
create your own copy of this file by hand and specify its path with
packagelistLoc . An example would be the previous case where the package list
for com.spipackage did not exist when com.apipackage was first generated. This
technique is useful when you need to generate documentation that links to new
external documentation whose package names you know, but which is not yet
published. This is also a way of creating package-list files for packages
generated with Javadoc 1.0 or 1.1, where package-list files were not generated.
Likewise, two companies can share their unpublished package-list files,
enabling them to release their cross-linked documentation simultaneously.
Linking to Multiple Documents -
You can include
-linkoffline once for
each generated document you want to refer to (each option is shown on a
separate line for clarity):
Tag | Description |
|
example% javadoc -linkoffline docURL1 packagelistURL1 \
-linkoffline docURL2 packagelistURL2 \
...
|
|
Updating Docs - Another use for the
-linkoffline option is useful if
your project has dozens or hundreds of packages; if you have
already run
javadoc on the entire tree; and now, in a
separate run, you want to quickly make some small changes and
re-run
javadoc on just a small portion of the source tree.
This is somewhat of a hack in that it works properly only if
your changes are only to doc comments and not to signatures.
If you were to add, remove, or change any signatures from the
source code, then broken links could show up in the index,
package tree, inherited member lists, use page, or other
places.
First, you create a new destination directory (call it update)
for this new
small run. Set the first argument of
-linkoffline to the current directory "." and
set the second argument to the relative path to the
original docs (call it html), where it
can find
package-list:
Tag | Description |
|
example% javadoc -d update -linkoffline . html com.mypackage
|
|
When
javadoc is done, copy these generated files (not the overview or index)
in
update over the original files in
Tag | Description |
-linksource
| |
Creates an HTML version of each source file (with line numbers) and adds links
to them from the standard HTML documentation. This option exposes all
private implementation details in the included source files, including
private classes, private fields, and the bodies of private methods,
regardless of the -public, -package, -protected and -private options. Unless
you also use the -private option, not all private classes or interfaces will
necessarily be accessible via links.
|
-group groupheading packagepattern:packagepattern:... | |
Separates packages on the overview page into whatever groups
you specify, one group per table.
You specify each group with
a different
-group option.
The groups appear on the page in
the order specified on the command line; packages are
alphabetized within a group.
For a given
-group option, the
packages matching the list of
packagepattern expressions appear in a table with the heading
groupheading.
Tag | Description |
o
|
groupheading can be any text, and can include white space.
This text is placed in the table heading for the group.
|
o
|
packagepattern can be any package name, or can be the
start of any package name followed by an asterisk (*).
The asterisk is a wildcard meaning "match any
characters".
This is the only wildcard allowed.
Multiple patterns can be included in a group by separating them
with colons (:).
|
NOTE: If using an asterisk in a pattern or pattern
list, the pattern list must be inside quotes, such
as "java.lang*:java.util".
If you do not supply any
-group option, all packages are
placed in one group with the heading "Packages".
If the all
groups do not include all documented packages, any leftover
packages appear in a separate group with the heading "Other
Packages".
For example, the following option separates the four
documented packages into core, extension, and other packages.
Notice the trailing "dot" does not appear in "java.lang*";
including the dot, such as "java.lang.*", would omit the
java.lang package:
Tag | Description |
|
example% javadoc -group "Core Packages" "java.lang*:java.util" \
-group "Extension Packages" "javax.*" \
java.lang java.lang.reflect java.util javax.servlet java.new
|
|
This results in the groupings:
Tag | Description |
|
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
|
|
|
-nodeprecated | |
Prevents the generation of any deprecated API at all in the
documentation.
This does what
-nodeprecatedlist does, plus it
does not generate any deprecated API throughout the rest of
the documentation.
This is useful when writing code and you
dont want to be distracted by the deprecated code.
|
-nodeprecatedlist | |
Prevents the generation of the file containing the list of
deprecated APIs (deprecated-list.html) and the link in the
navigation bar to that page.
(However,
javadoc continues to
generate the deprecated API throughout the rest of the
document.) This is useful if your source code contains no
deprecated API, and you want to make the navigation bar cleaner.
|
-nosince |
Omits from the generated docs the "Since" sections associated with the
@since tags.
|
-notree |
Omits the class/interface hierarchy from the generated docs.
The hierarchy is produced by default.
|
-noindex |
Omits the index from the generated docs.
The index is
produced by default.
|
-nohelp |
Omits the HELP link in the navigation bars at the top and
bottom of each page of output.
|
-nonavbar | |
Prevents the generation of the navigation bar, header and
footer, otherwise found at the top and bottom of the
generated pages.
Has no effect on the "bottom" option.
The
-nonavbar option is useful when you are interested only in
the content and have no need for navigation, such as
converting the files to PostScript or PDF for print only.
|
-helpfile path/filename | |
Specifies the path of an alternate help file
path/filename that the HELP link in the top and bottom navigation bars link
to. Without this option, the
Javadoc tool automatically creates a help file
help-doc.html that is hard-coded in the
Javadoc tool.
This option
enables you to override this default.
The filename can be any
name and is not restricted to help-doc.html;
the
Javadoc tool will adjust the links in the navigation bar accordingly.
For example:
Tag | Description |
|
example% javadoc -helpfile /home/doc/myhelp.html java.awt
|
|
|
-stylesheetfile path/filename | |
Specifies the path of an alternate HTML stylesheet file.
Without this option, the
Javadoc tool automatically creates a
stylesheet file,
stylesheet.css, that is hard-coded in the
Javadoc tool.
This option enables you to override this default.
The filename can be any name and is not restricted to
stylesheet.css. For example:
Tag | Description |
|
example% javadoc -stylesheetfile \
/home/user/mystylesheet.css com.mypackage
|
|
|
-serialwarn | |
Generates compile-time warnings for missing
@serial tags.
By default,
Javadoc 1.2.2 (and later versions) generates no serial warnings.
(This is a reversal from earlier versions.) Use this option to
display the serial warnings, which helps
to properly document default serializable fields and
writeExternal methods.
|
-charset name | |
Specifies the HTML character set for this document.
For example:
Tag | Description |
|
% javadoc -charset "iso-8859-1" mypackage
|
would insert the following line in the head of every
generated page:
<META http-equiv="Content-Type" content="text/html; charset=iso-885 9-1">
This META tag is described in the HTML standard
(4197265 and 4137321).
|
-docencoding name | |
Specifies the encoding of the generated HTML files.
|
-keywords | |
Adds HTML meta keyword tags to the
generated file for each class. These tags
can help the page be found by search engines
that look for meta tags. (Most
search engines that search the entire Internet
do not look at meta tags, because
pages can misuse them; but search engines offered
by companies that confine
their search to their own website can
benefit by looking at meta tags.)
|
The meta tags include the fully qualified
name of the class and theunqualified
names of the fields and methods.
Constructors arenot included because they are
identical to the class name. For example,
the class String starts with these keywords:
Tag | Description |
|
<META NAME="keywords" CONTENT="java.lang.String class">
<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
<META NAME="keywords" CONTENT="length()">
<META NAME="keywords" CONTENT="charAt()">
|
|
Tag | Description |
-tagtagname:Xaoptcmf: | |
Enables javadoc to interpret a simple, one-argument custom standalone tag
@tagname in doc comments. So the Javadoc tool can "spell-check" tag names, it
is important to include a
-tag option for every custom tag that is present in the
source code, disabling (with X) those that are not
being output in the current run.
|
The colon (:) is always the separator. To use a colon, see
Use of Colon in Tag Name . |
The -tag option outputs the tags heading taghead
in bold, followed on the next
line by the text from its single argument, as
shown in the example below. Like
any standalone tag, this arguments text can
contain inline tags, which are also
interpreted. The output is similar to standard
one-argument tags, such as
@return and @author.
|
Placement of tags -
The Xaoptcmf part of the argument determines where in
the source code the tag is allowed to be
placed, and whether the tag can be
disabled (using X). You can supply either a,
to allow the tag in all places, or any
combination of the other letters:
|
|
X (disable tag)
a (all)
o (overview)
p (packages)
t (types, that is classes and interfaces)
c (constructors)
m (methods)
f (fields)
|
|
Examples of single tags -
An example of a tag option for a tag that can be
used anywhere in the source code is:
|
|
|
If you wanted @todo to be used only with constructors,
methods and fields, you would use:
|
|
|
Notice the last colon (:) above is not a
parameter separator, but is part of the
heading text (as shown below). You
would use either tag option for source code
that contains the tag @todo, such as:
|
|
@todo The documentation for this method needs work.
|
|
This line would produce output something like:
|
|
To Do:
The documentation for this method needs work.
|
Tag | Description |
|
Use of Colon in Tag Name -
A colon can be used in a tag name if it
is escaped with a backslash. For this comment:
/**
* @ejb:bean
*/
|
|
use this tag option:
Tag | Description |
|
-tag ejb\:bean:a:"EJB
|
Spell-checking tag names (Disabling tags) -
Some developers put custom
tags in the source code that they dont
always want to output. In these cases, it
is important to list all tags that are
present in the source code, enabling the ones
you want to output and disabling the ones you
dont want to output. The
presence of X disables the tag, while its absence
enables the tag. This gives the
Javadoc tool enough information to know if a tag it encounters is unknown,
probably the results of a typo or a
misspelling. It prints a warning in these cases.
You can add X to the placement values already
present, so that when you want
to enable the tag, you can simply delete
the X. For example, if @todo is a tag that
you want to suppress on output, you would use:
or, if youd rather keep it simple:
The syntax -tag todo:X works even if @todo is defined by a taglet.
Order of tags -
The order of the -tag (and -taglet) options determine the
order the tags are output. You can mix the
custom tags with the standard tags to
intersperse them. The tag options for standard tags
are placeholders only for
determining the order -- they take only the
standard tags name. (Subheadings
for standard tags cannot be altered.) This is
illustrated in the following example.
If -tag is missing, then the position of -taglet
determines its order. If they are
both present, then whichever appears
last on the command line determines its
order. (This happens because the tags and
taglets are processed in the order that
they appear on the command line. For
example, if -taglet and -tag both have
the name "todo", the one that appears
last on the command line will determine
its order.
Example of a complete set of tags -
This example inserts "To Do" after
"Parameters" and before "Throws" in the output. By using "X", it also specifies
that @example is a tag that might be encountered in the source code that should
not be output during this run. Notice that if you use @argfile, you can put the
tags on separate lines in an argument file like this (no line continuation
characters needed):
Tag | Description |
|
,nf
-tag param
-tag return
-tag todo:a:"To Do:"
-tag throws
-tag see
-tag example:X
|
When javadoc parses the doc comments, any tag encountered that is neither a
standard tag nor passed in with -tag or -taglet is considered unknown, and a
warning is thrown.
The standard tags are initially stored internally
in a list in their default order.
Whenever -tag options are used,
those tags get appended to this list --
standard tags are moved from their default position.
Therefore, if a -tag option
is omitted for a standard tag, it
remains in its default position.
Avoiding Conflicts -
If you want to slice out your own namespace, you can use
a dot-separated naming convention similar to
that used for packages:
com.mycompany.todo. Sun will continue to
create standard tags whose names do
not contain dots. Any tag you create will
override the behavior of a tag by the
same name defined by Sun. In other words, if you create
a tag or taglet @todo, it
will always have the same behavior you define,
even if Sun later creates a
standard tag of the same name.
You can also create more complex standalone tags, or custom inline tags with
the -taglet option.
Tag | Description |
-taglet " class"
| |
Specifies the class file that starts the taglet used in
generating the documentation for that tag. Use the
fully-qualified name for
class . This taglet also
defines the number of text arguments that the custom
tag has. The taglet accepts those arguments, processes
them, and generates the output. For extensive
documentation with example taglets, see Taglet Overview.
|
Taglets are useful for standalone or inline tags.
They can have any number of arguments and
implement custom behavior, such as making
text bold, formatting bullets, writing out the text to a file,
or starting other processes.
|
Use the
-tagletpath option to specify the path to the taglet.
Here is an example that inserts the "To
Do" taglet after "Parameters" and ahead
of "Throws" in the generated pages:
|
|
-taglet com.sun.tools.doclets.ToDoTaglet
-tagletpath /home/taglets
-tag return
-tag param
-tag todo
-tag throws
-tag see
|
|
Alternatively, you can use the
-taglet option in place of its
-tag option, but that may be harder to read.
|
-tagletpath " tagletpathlist"
| |
Specifies the search paths for finding taglet
class files (.class). The
tagletpathlist can contain multiple
paths by separating them with a colon (:). The
Javadoc tool will search in all subdirectories of the
specified paths.
|
-subpackages " package1:package2:..."
| |
Generates documentation from source files in
the specified packages and recursively in their
subpackages. This option is useful when adding
new subpackages to the source code, as they are
automatically included. Each
package is any top-level
package (java) or fully qualified subpackage
javax.swing), and does not need to contain source files.
Wildcards are not needed or allowed.
Use
-sourcepath to specify where to find the packages. For example:
% javadoc -d docs -sourcepath /home/user/src \
-subackages java:javax.swing
|
|
This command generates documentation for packages
name "java" and "javax.swing" and all their subpackages.
|
There is also an option to exclude subpackages as it traverses
the subpackages.
|
-exclude " packagename1:packagename2:..."
| |
Unconditionally excludes the specified packages
and their subpackages from the list formed by
-subpackages. It excludes those packages even
if they would otherwise be included by some
previous or later -subpackages option. For example:
% javadoc -sourcepath /home/user/src -sourcepath java\
-exclude java.net:java.lang
|
|
would include
java.io, java.util, and
java.math (among others), but would exclude packages
rooted at
java.net and
java.lang. Notice this excludes
java.lang.ref, a subpackage of
java.lang). |
-breakiterator
| |
Uses the internationalized sentence boundary
of
java.text.BreakIterator to determine the end of the first
sentence for English (all other
locales already use
BreakIterator ), rather than an English language,
locale-specific algorithm. By first
sentence, we mean the first sentence in the main
desription of a package, class or member.
This sentence is copied to the package, class
or member summary, and to the alphabetic index.
|
From JDK 1.2 forward, the
BreakIterator class is already used to determine the end of sentence for all
languages but English. Therefore, the -breakiterator
option has no effect except for English
from 1.2 forward. English
had its own default algorithm:
|
o
|
English default sentence break algorithm -
Stops at a period followed by a space or
a HTML block tag, such as <P>.
|
o
|
Breakiterator sentence break algorithm -
Stops at a period, question mark or
exclamation mark followed by a space if the next word
starts with a capital letter. This is meant to handle
most abbreviations (such as "The serial no. is valid", but
wont handle "Mr. Smith"). Wont stop at HTML tags
or sentences that begin with numbers or symbols.
Stops at the last period in "../filename", even if
embedded in an HTML tag.
|
NOTE: We have removed from 1.5.0
the breakiterator warning
messages that were in 1.4.x and
have left the default sentence-break
algorithm unchanged. That is, the
-breakiterator option is not the
default in 1.5.0, nor do we expect it
to become the default. This is a
reversal from our former intention that
the default would change in
the "next major release" (1.5.0). This
means if you have not modified
your source code to eliminate the breakiterator
warnings in 1.4.x, then
you dont have to do anything, and
the warnings go away starting with
1.5.0. The reason for this reversal is
because any benefit to having
breakiterator become the default
would be outweighed by the
incompatible source change it would
require. We regret any extra
work and confusion this has caused.
|
-docfilessubdirs
| |
Enables deep copying of "doc-files" directories.
In other words, subdirectories and all contents
are recursively copied to the destination.
For example, the directory
doc-files/example/images and all its contents would now be copied.
There is also an option to exclude subdirectories.
|
-excludedocfilessubdirs " name1:name2:..."
| |
Excludes any "doc-files" subdirectories with the
given names. This prevents the copying of SCCS
and other source-code-control subdirectories.
|
-noqualifier " all | packagename1:packagename2:..."
| |
Omits qualifying package name from ahead of
class names in output. The argument to
-noqualifier is either "all" (all
package qualifiers are omitted) or a colon-separate list of
packages, with wildcards, to be removed
as qualifiers. The package name is removed from places
where class or interface names appear.
|
The following example omits all package qualifiers:
|
|
|
The following example omits "java.lang"
and "java.io" package qualifiers:
|
|
-noqualifier java.lang:java.io
|
|
The following example omits package qualifiers
starting with "java", and "com.sun"
subpackages (but not "javax"):
|
|
-noqualifier java.*:com.sun.*
|
|
Where a package qualifier would appear due
to the above behavior, the following
behavior (present in 1.3) also takes effect
to further omit qualifiers: On the page for
class
p.C, remove the package qualifier for classes
belonging to package
p. This rule is present whether or not
-noqualifier is used.
|
-notimestamp | |
Suppresses the timestamp, which is
hidden in an HTML comment in the
generated HTML near the top of each page.
Useful when you want to run javadoc
on two source bases and diff them, as
it prevents timestamps from causing a
diff (which would otherwise be a diff on
every page). The timestamp includes the
javadoc version number,and currently looks like this:
|
Tag | Description |
|
<!-- Generated by javadoc (build 1.5.0-internal)
on Tue Jun 22 09:57:24 PDT 2004 -->
|
-nocomment
| |
Suppress the entire comment body,
including the description and all tags,
generating only declarations. This
option enables re-using source files
originally intended for a different purpose, to
produce a skeleton perhaps for a new project.
|
|
|
|
Command Line Argument Files
TO shorten or simplify the javadoc command line,
you can specify one or more files that themselves
contain arguments to the
javadoc command (except -J options).
This enables you to create
javadoc commands of any length on any operating system.
An argument file can include Javadoc options,
source filenames and package names in
any combination, or just arguments to
Javadoc options. The arguments within a file
can be space-separated or
newline-separated. Filenames within an argument
file are relative to the current directory,
not the location of
the argument file. Wildcards (*) are not allowed
in these lists (such as for specifying *.java).
Use of the @
character to recursively interpret files
is not supported. The -J options are not
supported because they are
passed to the launcher, which does not
support argument files.
When executing
javadoc, pass in the path and name of each
argument file with the @ leading
character. When
javadoc encounters an argument beginning with
the character @, it expands the
contents of that file in the argument list.
Example - Single Arg File
You could use a single argument file named "argfile"
to hold all Javadoc arguments:
This argument file could contain the contents of
both files shown in the next example.
Example - Two Arg Files
You can create two argument files - one for the Javadoc
options and the other for the package names or
source filenames: (Notice the following lists have
no line-continuation characters.)
Create a file named "options" containing:
-d docs-filelist
-use
-splitindex
-windowtitle Java 2 Platform v1.3 API Specification
-doctitle Java<sup><font size="-2">TM</font></sup> 2\
Platform v1.4 API Specification
-header <b>Java 2 Platform </b><br><font size="-1">v1.4</font>
-bottom Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.
-group "Core Packages" "java.*"
-overview /java/pubs/ws/1.3/src/share/classes/overview-core.html
-sourcepath /java/pubs/ws/1.3/src/share/classes
|
Create a file named "packages" containing:
com.mypackage1
com.mypackage2
com.mypackage3
|
You would then run javadoc with:
% javadoc @options @packages
|
Example - Arg Files with Paths
The argument files can have paths, but
any filenames inside the files are relative
to the current working directory (not path1 or path2):
% javadoc @path1/options @path2/packages
|
Examples - Option Arguments
Heres an example of saving just an
argument to a javadoc option in an argument file.
Well use the -bottom
option, since it can have a lengthy
argument. You could create a file named "bottom" containing its text
argument:
Submit a bug or feature</a><br><br>Java is a
trademark or registered trademark of
Sun Microsystems, Inc. in the US and other
countries.<br>Copyright 1993-2000 Sun
Microsystems, Inc. 901 San Antonio Road,<br>Palo
Alto, California, 94303, U.S.A.
All Rights Reserved.</font>
The run the
Javadoc tool with:
% javadoc -bottom @bottom @packages
|
Or you could include the -bottom
option at the start of the argument file,
and then just run it as:
% javadoc @bottom @packages
|
RUNNING
|