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