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 hypertext document. You can pass either a package or specific Java source files to . In addition to the usual comments, javadoc uses a special set of tags that it recognizes in the doc comments.

package must be in your CLASSPATH. Note that javadoc uses .java files not .class files.

javadoc reformats and displays all public and protected declarations for,

Classes and interfaces
Methods
Variables

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. Don't use tags like <h1> and <hr>,etc. 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 colons, for example:

    .:/home/avh/classes/:/usr/local/java/classes

-d directory

Specifies the directory where javadoc stores the generated HTML files. For example:

    javadoc -d ~/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 colons, for example,

    .:/home/avh/classes:/usr/local/java/classes