javadoc parses the declarations and documentation comments in
a set of Java source
files and produces a set of HTML pages describing, by default,
the public and protected classes, interfaces, constructors, methods,
and fields. As an argument to javadoc you pass
in either a series of Java package names or source files.
javadoc generates one .html file for each .java file and
each packages it encounters. In addition, it produces a class hierarchy
(tree.html) and an index of those members (AllNames.html).
When javadoc parses the class and member delarations, it
picks up their signatures for inclusion. In addition, you can
add further documentation by including doc comments in the source
code.
Commenting the Source Code
You can include documentation comments in the source code.
A doc comment consists of the characters between the
/** that begins the comment and the
*/ that ends it. The text is divided into one or more lines.
When javadoc parses a doc comment, leading * characters on each line
are discarded; for lines other than the first, blanks and tabs
preceding the initial * characters are also discarded. These
comments may include HTML tags. Here is a doc comment:
/**
* This is a <b>doc</b> comment.
*/
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 tag (as defined below).
javadoc copies this first sentence to the member summary
at the top of the .html file.
Documentation comments are only recognized when placed immediately before
class, interface, constructor, method, or field declarations.
When you embed HTML tags within a doc commen, you should not
use heading tags such as <h1> and <h2>, because
javadoc creates an entire structured document and these
structural tags interfere with the formatting of the generated
document.
For the specification on documentation comments, see Chapter 18,
Documentation Comments, in the Java Language Specification,
by James Gosling, Bill Joy, and Guy Steele.
Tagged Paragraphs
javadoc parses special tags that are recognized 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 (@).
Tags must start at the beginning of a line. Keep tags with the same
name together within a doc comment. For example, put all @author
tags together so that javadoc can tell where the list ends.
The tags fall into three categories: Class/interface tags, field tags,
and constructor/method tags; each is itemized in the following sections.
Class and Interface Documentation Tags
@authorname-text
Creates an "Author" entry. The text has no special internal structure.
A doc comment may contain multiple @author tags.
@versionversion-text
Adds a "Version" entry. 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 JDK)
that contains this feature.
@seeclassname
Adds a hyperlinked "See Also" entry to the class.
Some examples are:
Note 1 - This works only if equals is in the current class. First javadoc
looks for a field, then a method with that name.
Note 2 - This is the proper syntax in version 1.1.x if the @see statement is in a
class other than String.
Note 3 - Supplying a method argument type as shown will distinguish among methods with
the same name.
Note 4 - In version 1.1.x, the argument type must be fully-qualified, as shown.
Note that a URL (as follows) is not allowed in an @see tag in version 1.1.x: @see <a href="spec.html">Java Spec</a>
The workaround is to include this URL in the comment before the tags.
The character # separates the name of a class or interface from the name of one
of its fields, methods, or constructors.
One of several overloaded methods or constructors may be
selected by including a parenthesized list of argument types after the method
or constructor name.
Whitespace in @see's classname is significant.
If there is more than one argument, there must be a single blank character
between the arguments.
For example:
Adds a "Since" entry. The text has no special internal structure.
This tag means that this change or feature has existed since the release
number of the software specified by the since-text (such as the JDK).
@deprecateddeprecated-text
Adds a deprecated comment indicating that this API should no longer
be used (even though it may continue to work). The convention is to
describe the API that serves as a replacement. For example:
@deprecated Replaced by setBounds(int, int, int, int).
If the member is obsolete and there is no replacement, the argument
to @deprecated should be "No replacement".
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
Field Documentation Tags
A field comment can contain only the @see, @since
and @deprecated tags (as described above).
An example of a field comment:
/**
* The X-coordinate of the window.
*
* @see window#1
*/
int x = 1263732;
Constructor and Method Documentation Tags
Can contain @see tags, as well as:
@paramparameter-namedescription
Adds a parameter to the "Parameters" section. The description may
be continued on the next line.
@returndescription
Adds a "Returns" section, which contains the description of the return
value.
@exceptionfully-qualified-class-namedescription
Adds a "Throws" section, which contains the name of the exception that may
be
thrown by the method. The exception is linked to its class documentation.
@seeclassname
Adds a hyperlinked "See Also" entry to the method. This tag is
described above.
@sincesince-text
See the description above.
@deprecateddeprecated-text
See the description above.
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) {
...
}
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.
-Jflag
Pass flag directly to the runtime system. For example, if you need to
ensure that the system sets aside 32 megabytes of memory to hold the generated
documentation, then you would use this flag as follows:
javadoc -J-mx32m -J-ms32m <classes> ...
-encodingname
Specify the source file encoding name, such as EUCJIS\SJIS. If
this option is not specified, the platform default converter is used.
-docencodingname
Specify output HTML file encoding name.
-version
Include @version tags, which are omitted by default.
-author
Include @author tags, which are omitted by default.
-noindex
Omit the package index, which is produced by default.
-notree
Omit the class/interface hierarchy, which is produced by default.
-ddirectory
Specifies the destination directory where javadoc stores the
generated HTML files. (The "d" means "destination.") The directory can be
absolute or relative to the current working directory.
For example, the following generates the documentation for the java.lang
package (using CLASSPATH to find it) and stores the results in the directory
specified by the -d option:
javadoc -d C:\opus\public_html\doc java.lang
-verbose
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.
-sourcepathpath
Specifies the search path for source files. Does not affect the loading of
class files. The sourcepath you specify depends on whether you
specify packages or classes as arguments to the javadoc command.
When generating documentation for packages, specify sourcepath as
the directory in the source tree that contains the top-most parent package of
the packages you are documenting. The default for sourcepath
is the current classpath directory. For example, suppose you want
to document a package called java.lang whose source files are
located at:
C:\myapp\src\share\java\lang\*.java
Because java is the top-most parent package, you would specify
the sourcepath to be the directory that contains java:
-sourcepath C:\myapp\src\share
When generating documentation for discrete classes, specify sourcepath as the directory in the source tree that contains the classes you are
documenting. Note that this is different from the sourcepath
you used when documenting packages. For example, suppose you want to
document a class named java.lang.String whose source file is
located at:
C:\myapp\src\share\java\lang\String.java
Specify the sourcepath to be the directory that contains the
class String.java:
-sourcepath C:\myapp\src\share\java\lang
You can omit the sourcepath option if you first switch to the
directory you would have specified.
-classpathpath
NOTE: In general, do not use -classpath, because it is normally not
needed; use -sourcepath instead to specify .java files.
Specifies the directories from which javadoc is to load the
.class files used to execute the javadoc tool.
If -sourcepath is not specified, this also specifies the path
javadoc uses to look up the .java files to document.
It overrides the default or the CLASSPATH environment variable, if it is set.
The path can contain multiple paths by separating them with a colon.
Se the path the same way you do for the CLASSPATH
environment variable.
For example, the following sets two paths: current
directory (.) and C:\opus\myclasses:
The -classpath option is not necessary if you call
javadoc wrapper script directly. Normally, if you specify
classpath it must precede sourcepath.
However, the order of these two options does not matter if you are using the
wrapper script.
The value of classpath defaults to the current directory
plus the classes location, as described in the CLASSPATH environment variable.
-nodeprecated
Exclude paragraphs with the @deprecated tag.
NOTE: The -doctype option is no longer available. Only
HTML documentation
can be produced.
EXAMPLES
Each package name has a corresponding directory name.
In the following examples, the source files are located at
C:\ws\src\java\awt\*java. The destination
directory is C:\ws\html.
Documenting One or More Packages
To document a package, the source files (*.java) for that package
must be located in a directory having the same name as the package.
If a package name is made up of several identifiers (separated by
dots), each identifier represents a different directory.
Thus, all java.awt classes must reside in a directory named java\awt\.
First, change to the parent directory of the top-most package
(or supply the sourcepath option with that directory). Then
run javadoc, supplying one or more fully-specified package names.
For example, if
you want to document the source files in the java.awt
package located at C:\ws\src\java\awt\*.java and
its subpackage java.awt.event:
% cd C:\ws\src\
% javadoc -d C:\ws\html java.awt java.awt.event
This generates HTML-formatted documentation for the public classes
in packages java.awt and java.awt.event
and puts it in the specified destination directory
(C:\ws\html).
Documenting One or More Classes
Change to the directory containing the classes (or supply
the sourcepath option with that directory).
Then run javadoc, supplying one or more class names.
For example, to document classes at the same level as
C:\ws\src\java\awt\Button.java:
% cd C:\ws\src\java\awt
% javadoc -d C:\ws\html Button.java Canvas.java
This generates HTML-formatted documentation for the two classes
and puts it in the specified destination directory
(C:\ws\html).
ENVIRONMENT
CLASSPATH
Provides the system a path to the user-defined classes.
Separate directories with a semi-colon, for example,