javadoc - The Java API Documentation Generator

Generates HTML pages of API documentation from Java source files.

SYNOPSIS

javadoc options* packagename* sourcefile* @filename*

DESCRIPTION

javadoc parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, inner classes, interfaces, constructors, methods, and fields.

You can run javadoc on entire packages, individual classes or both. In the first case, you pass in as an argument to javadoc a series of package names. In the second case you pass in a series of source (.java) filenames. Examples are given at the end of this document.

When javadoc parses the class and member delarations, it picks up their signatures for inclusion in the output. In addition, you can add further documentation by including documentation comments in the source code.

By default, javadoc uses a standard doclet that generates HTML-formatted documentation. This doclet generates an .html file for each class and package it is documenting. In addition, it produces a class hierarchy (tree.html) for the system, a separate class hierarchy for each package, a list of deprecated API, a serialized form page, and an index of API names.

For information and workarounds for bugs in javadoc, refer to the Javadoc FAQ. For more information about how to write documentation comments, refer to How to Write Doc Comments for Javadoc.

Terminology

It is helpful to define a few terms:
generated document
The document generated by the javadoc tool from the doc comments in Java source code. The default generated document is in HTML and is created by the standard doclet.

name
A name in the Java Language, namely the name of a package, class, interface, field, constructor or method. A name can be fully-qualified, such as java.lang.String.equals(java.lang.Object), or partially-qualified, such as equals(Object).

documented classes
The classes and interfaces for which full documentation is generated during a javadoc run. To be documented, the source files must be available, and either their source filenames or package names must be passed into the javadoc command. We also refer to these as the classes included in the javadoc run, or the included classes.

referenced classes
The classes and interfaces that are explicitly referred to in the definition of the documented classes and interfaces. Examples of references include return type, parameter type, cast type, extended class, implemented interface, imported classes, and so forth. Classes referred to in doc comments (such as @see tags) do not qualify as referenced classes. When Javadoc is run, it loads into memory all of the referenced classes in javadoc's bootclasspath and classpath. (Javadoc prints a "Class not found" warning for referenced classes not found.) Javadoc can derive enough information from the the .class files to determine their existence and the fully-qualified names of its members. That plus their documentation URL allows their docs to be linked to.

external referenced classes
The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are external to that javadoc run. Links for names in the documentation to those classes are said to be external references or external links. For example, if you run javadoc on only the java.awt package, then then any class in java.lang, such as Object, is an external referenced class.

Javadoc Doclets

You can customize the content and format of javadoc's output by using doclets. Information about doclets and their use is at the following locations: When a custom doclet is not specified with the -doclet command line option, javadoc will use the default standard doclet that produces HTML-formatted API documentation. The javadoc tool has several command line options that are available regardless of which doclet is being used. The standard doclet adds a supplementary set of command line options. Both sets of options are described below in the options section.

Commenting the Source Code

You can include documentation comments in the source code, ahead of declarations for any entity (classes, interfaces, methods, constructors, or fields). A doc comment consists of the characters between the characters /** that begin the comment and the characters */ that end it. The text is divided into one or more lines. When javadoc parses a doc comment, leading * characters on each line are discarded; blanks and tabs preceding the initial * characters are also discarded. These comments may include HTML tags. Here is a doc comment: 

/**
 * This is a <b>doc</b> comment.
 */

The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). javadoc copies this first sentence to the member summary at the top of the .html file.

Documentation comments are only recognized when placed immediately before class, interface, constructor, method, or field declarations.

When you embed HTML tags within a doc comment, you should not use heading tags such as <h1> and <h2>, because javadoc creates an entire structured document and these structural tags interfere with the formatting of the generated document.

For the specification on documentation comments, see Chapter 18, Documentation Comments, in the Java Language Specification, by James Gosling, Bill Joy, and Guy Steele.

Tagged Paragraphs

javadoc parses special tags when they are embedded within a 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 (after any leading spaces and an optional asterisk). By convention, keep tags with the same name together. For example, put all @see tags together.

For information about proposed tags, see Proposed Tags.

@author  name-text
Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. The text has no special internal structure. A doc comment may contain multiple @author tags.

@deprecated  deprecated-text
Adds a comment indicating that this API should no longer be used (even though it may continue to work). The convention is to describe the API that serves as a replacement. For example: 
    @deprecated  Replaced by setBounds(int, int, int, int).
If the member is obsolete and there is no replacement, the argument to @deprecated should be "No replacement".

For more about this tag, see The @deprecated tag.

@exception  class-name  description
The @exception tag is a synonym for @throws.

{@link  name  label}
Inserts an in-line link that points to the specified name. This tag accepts exactly the same syntax for name and label as the @see tag, described immediately above, but generates an in-line link rather than placing the link in the "See Also" section. This tag begins and ends with curly braces to separate it from the rest of the in-line text.

For example, here is a comment that refers to the getComponentAt(int, int) method: 

Use the {@link getComponentAt(int, int) getComponentAt} method.
From this, the standard doclet would generate the following HTML: 
Use the <a href="Component#getComponentAt(int, int)">getComponentAt</a> method.
Which appears on the web page as: 
Use the getComponentAt method.
@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 with the description text. This text should describe the return type and permissible range of values.

@see  reference
Adds a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, which are all grouped under the same heading. The @see tag has three variations:

@see  package.class#member  label
Adds a link, with visible text label, that points to the documentation for the specified name in the Java Language. The label is optional; if omitted, the name appears instead. Use the label when you want the visible text to be abbreviated or different from the name. This form is described in greater detail below, along with examples.

@see <a href="URL#value">label</a>
Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. Javadoc distinguishes this from the previous case by looking for a less-than symbol (<) as the first character. An example is shown below.

@see "string"
Adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL. Javadoc distinguishes this from the previous cases by looking for a double-quote (") as the first character. An example is shown below.

The second and third forms above are straightforward; the first forms requires further elaboration. The two arguments to the first form are as follows:

  • package.class#member is any valid name in the Java Language -- the name of a package, class, interface, constructor, method or field -- except that the hash character replaces the dot ahead of the member name. If this name belongs to the documented classes, Javadoc will automatically create a link to it. To create links to external referenced classes, use the -link option. Use either of the other two @see forms for referring to documentation of a name that does not belong to a referenced class.

    This name can be either fully-qualified or partially-qualified. If partially-qualified, javadoc uses the normal javac compiler search order to fully-qualify it, further described below in Search order for @see. The name can contain whitespace within parentheses, such as between method argument types.

    Of course the advantage to providing shorter, partially-qualified names is that it is less to type and easier to read in the source code. The follow are the different forms of the name, where Class can be a class or interface, Type can be a class, interface, array, or primitive, and method can be a method or constructor.

    As stated in Note 1 below, the first four forms (that begin with #) work only if the name is in the current class or interface, one of its superclasses or superinterfaces, or one of its enclosing classes or interfaces.

    Partially- and Fully-Qualified Names for @see
    @see  #field
    @see  #method
    @see  #method(Type, Type,...)
    @see  #method(Type argname, Type argname,...)
    @see  Class
    @see  Class#field
    @see  Class#method
    @see  Class#method(Type, Type,...)
    @see  Class#method(Type argname, Type argname,...)
    @see  package.Class
    @see  package.Class#field
    @see  package.Class#method
    @see  package.Class#method(Type, Type,...)
    @see  package.Class#method(Type argname, Type argname,...)
    @see  package     		[Note 1]
    [Note 1]
    [Note 1]
    [Note 1]
    [Note 2]

    Note 1 - The forms with no class or package will search only through the current class's hierarchy (search steps 1-3), and will not search the rest of the current package or other packages (search steps 4-5).

    Note 2 - Inner classes must be specified as outer.inner, not simply inner, for all forms.

    You can select one of several overloaded methods or constructors by fully-qualifying it -- that is, including its parenthesized list of argument types.

    Notice that the hash character (#), rather than a dot (.) separates a member from its class. This enables Javadoc to resolve ambiguities, since the dot also separates classes, inner classes, packages, and subpackages. The hash character is absolutely necessary in the first five forms above, when it is the first character. However, in other cases, Javadoc is generally forgiving and will allow a dot if it does not produce an ambiguity, though it will print a warning. Notice that you can omit the parentheses from a constructor or method if there is no ambiguity (that is, if there is no field by thathis enables Javadoc to resolve ambiguities, since the dot also separates classes, inner classes, packages, and subpackages. The hash character is absolutely necessary in the first five forms above, when it is the first character. However, in other cases, Javadoc is generally forgiving and will allow a dot if it does not produce an ambiguity, though it will print a warning. Notice that you can omit the parentheses from a constructor or method if there is no ambiguity (that is, if there is no field by that