javadoc - The Java API Documentation Generator

Generates HTML pages of API documentation from source files.

SYNOPSIS

javadoc [ options ] package | class1.java class2.java...

DESCRIPTION

javadoc parses the declarations and documentation comments in a set of Java source files and produces a set of HTML pages describing the public and protected classes, constructors, methods, and fields. In addition, it produces a list of classes, a class hierarchy and an index of all APIs. As an argument to javadoc you must pass in either a package name or a series of Java source files. By default javadoc produces HTML pages; however the doctype option allows you to produce MIF files for import into FrameMaker.

Commenting the Source Code
While javadoc automatically parses class, interface, methods and variable declarations, you can add further documentation via doc comments in the source code. These comments may include HTML tags. 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. On each of these lines, leading * characters are ignored; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded.
/**
*  This is a doc 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 tagline (as defined below).
Documentation comments are only recognized when placed immediately before class, constructor, method, or field declarations.
Standard HTML

You can embed standard HTML tags within a doc comment. You should not use heading tags such as <h1> and <h2>, or a horizontal rule <hr>, because javadoc creates an entire structured document and these structural tags interfere with the formatting of the generated document.

javadoc Tags

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.

Class and Interface Documentation Tags
@see classname
Adds a hyperlinked "See Also" entry to the class. Some examples are:
	@see java.lang.String
	@see String
	@see String#equals
	@see java.lang.Object#wait(int)
	@see Character#MAX_RADIX
	@see <a href="spec.html">Java Spec</a>
The character # separates the name of a class 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. A doc comment may contain more than one @see tag.
@version version-text
Adds a "Version" entry. The text has no special internal structure. A doc comment may contain at most one @version tag.

@author name-text
Creates an "Author" entry. The text has no special internal structure. A doc comment may contain multiple @author tags.
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>
 *
 * @see            awt.BaseWindow
 * @see            awt.Button
 * @version        1.2 12 Dec 1994
 * @author         Sami Shaio
 */
class Window extends BaseWindow {
        ...
}
Field Documentation Tags
The only special tag a field comment can contain is the @see tag (as described above).
An example of a variable 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:

@param parameter-name description...
Adds a parameter to the "Parameters" section. The description may be continued on the next line.

@return description...
Adds a "Returns" section, which contains the description of the return value.

@exception fully-qualified-class-name description...
Adds a "Throws" entry, which contains the name of the exception that may be thrown by the method. The exception is linked to its class documentation.

An example of a method comment:
/**
 * Return the character at the specified index. An index 
 * ranges from <tt>0</tt> to <tt>length() - 1</tt>.
 * @param index      The index of the desired character
 * @return           The desired character
 * @exception        StringIndexOutOfRangeException 
 *                   Occurs when the index is not in
 *                   the range <tt>0</tt> 
 *                   to <tt>length() - 1</tt>.
 */
public char charAt(int index) {
    ...
}

OPTIONS

-classpath path
Specifies the path javadoc uses to look up the .java files. Also specifies the directories from which javadoc is to load its own .class files. (Use -sourcepath to specify a source path separately.) Each path element should be a directory that contains the topmost packages. Overrides the default or the CLASSPATH environment variable, if it is set. The path can contain multiple paths by separating them with a colon. For example, the following sets two paths, the first of which is the current directory (.):
javadoc -classpath .:/home/opus/javasrc
-version
Include @version tags, which are ommitted by default.

-author
Include @author tags, which are ommitted by default.

-doctype type
Produce documentation of type type, either HTML (default) or MIF (FrameMaker Interface Format).

-noindex
Omit the package index, which is produced by default.

-notree
Omit the class/interface hierarchy, which is produced by default.

-d directory
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 /home/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.
-sourcepath path
Specifies the search path for source files. Does not affect the loading of class files.

EXAMPLES

javadoc -classpath /home/wise/src java.io
Generates HTML-formatted documentation for all classes, interfaces, methods and variables in the Java source files belonging to the java.io package located below the specified directory:
/home/wise/src

ENVIRONMENT

CLASSPATH
Provides the system a path to the user-defined classes to be processed by javadoc. Separate directories with a colon, for example,
.:/home/avh/classes:/usr/local/java/classes

javadoc - The Java API Documentation Generator

SYNOPSIS

DESCRIPTION

Commenting the Source Code

Standard HTML

javadoc Tags

Class and Interface Documentation Tags

An example of a class comment:

Field Documentation Tags

An example of a variable comment:

Constructor and Method Documentation Tags

An example of a method comment:

OPTIONS

EXAMPLES

ENVIRONMENT

SEE ALSO