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 doc comments in Java source files and formats the public and protected API into a set of HTML pages. In addition, it produces a list of classes, a class hierarchy and an index of all API. As an argument to javadoc you can 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.

------

It does this by copying the javadoc comments and other relevant information from the .java files, adding HTML tags, and saving the resulting files to the current directory. Notice that classpath is set to one directory above the io directory that actually contains the .java files. That is, it looks for the source files in this location: 

/home/dhk/javasrc/src/share/java/java/io/
Adding the verbose option would allow you to monitor the processing.

------

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.

Commenting the Source Code

While javadoc will automatically parse the class, interface, method and variable declarations for some of its documentation, you can add further documentation inside doc comments, including special formatting with HTML tags.

Doc Comments

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

/**
*  This is a doc comment
*
*/

Standard HTML

You can embed standard HTML tags within a doc comment. However, don't 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 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 "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 your @author tags together so javadoc can tell where the list ends.

The following sections describe how to comment your source code for classes, variables, and methods (interfaces are documented the same as classes):

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

The only special tag a variable 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;

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. The path should be set to the directory that contains the topmost package. 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/dhk/javasrc/src/share/java/java
-version ???
Specifies the ... javadoc s.... [WHERE DOES THE VERSION FIELD APPEAR?] For example: 
javadoc -? ? java.lang
-author ???
Specifies the ... javadoc s.... For example: 
javadoc -? ? java.lang
-doctype ???
Specifies the ... javadoc s.... For example: 
javadoc -? ? java.lang
-noindex ???
Specifies the ... javadoc s.... For example: 
javadoc -? ? java.lang
-notree ???
Specifies the ... javadoc s.... For example: 
javadoc -? ? java.lang
-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/dkramer/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 API. The verbose option causes the printing of additional messages specifying the number of milliseconds to parse each java source file.
-sourcepath ???
Synonym for -classpath.

EXAMPLES

javadoc -classpath /home/dhk/javasrc/src/share/java 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 directory specified by classpath. It looks for the source files in this location: 
/home/dhk/javasrc/src/share/java/java/io/
javadoc -classpath /home/dhk/javasrc/src/share/java java.io
Generates documentation for the packages java.io. 
javadoc java.io.PrintStream.java
Generates documentation for the classes java.io.PrintStream.java [or java.io.PrintStream?].

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

SEE ALSO

javac, java, jdb, javah, javap,