javadoc - The Java API Documentation Generator

Generates API documentation from source files.

SYNOPSIS

javadoc [ options ] package | filename.java...

DESCRIPTION

javadoc parses the declarations and doc comments in Java source files and formats the public API into a set of HTML pages. As an argument to javadoc you can pass in either a package name or a list of Java source files.

Within doc comments, javadoc supports the use of special doc tags to augment the API documentation. javadoc also supports standard HTML within doc comments. This is useful for code samples and for formatting text.

The package specified on the command line must be in your CLASSPATH. Note that javadoc uses .java files not .class files.

javadoc reformats and displays all public and protected declarations for,

Doc Comments

Java source files can include doc comments. Doc comments begin with /** and indicate text to be included automatically in generated documentation.

Standard HTML

You can embed standard html tags within a doc comment. However,don't use tags heading tags like <h1> or <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 an Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an @.

Tags must start at the beginning of a line. Keep tags with the same name together within a doc comment. For example, put all your @author tags together so javadoc can tell where the list ends.

Class Documentation Tags

@see classname
Adds a hyperlinked "See Also" entry to the class.
@see fully-qualified-classname
Adds a hyperlinked "See Also" entry to the class.
@see fully-qualified-classname#method-name
Adds a hyperlinked "See Also" entry to the method in the specified class.
@version version-text
Adds a "Version" entry.
@author your-name
Creates an "Author" entry. There can be 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 {
        ...
}

Variable Documentation Tags

In addition to HTML text, variable comments can contain only the @see tag (see above).

An example of a variable comment:

/**
 * The X-coordinate of the window
 * @see window#1
 */
int x = 1263732;

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 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. Overrides the default or the CLASSPATH environment variable, if it is set. Directories are separated by semi-colons, for example: 
.;C:\users\dac\classes;C:\tools\java\classes
-d directory
Specifies the directory where javadoc stores the generated HTML files. For example: 
javadoc -d C:\usrs\dac\public_html\doc java.lang
-verbose
Causes the compiler and linker to print out messages about what source files are being compiled and what object files are being loaded.

ENVIRONMENT VARIABLES

CLASSPATH
Used to provide the system a path to user-defined classes. Directories are separated by semi-colons, for example, 
.;C:\users\dac\classes;C:\tools\java\classes

SEE ALSO

javac, java, jdb, javah, javap,