Generates HTML pages of API documentation from Java source files.
javadoc [ options ] [ package | source.java ]*
javadoc parses the declarations and documentation comments in a set of Java source files and produces a set of HTML pages describing, by default, the public and protected classes, inner classes, interfaces, constructors, methods, and fields. As an argument to javadoc you pass in either a series of Java package names or source files.By default, javadoc generates one .html file for each .java file and each packages it encounters. In addition, it produces a class hierarchy (tree.html) and an index of class members.
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.
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-format 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.
You can include documentation comments in the source code. A doc comment consists of the characters between the/**
that begins the comment and the*/
that ends it. The text is divided into one or more lines. When javadoc parses a doc comment, leading * characters on each line are discarded; for lines other than the first, 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 commen, 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.
javadoc parses special tags that are recognized 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. Keep tags with the same name together within a doc comment. For example, put all @author tags together so that javadoc can tell where the list ends.
The tags fall into three categories: Class/interface tags, field tags, and constructor/method tags; each is itemized in the following sections.
@author
name-text- Creates an "Author" entry. The text has no special internal structure. A doc comment may contain multiple
@author
tags.
@version
version-text- Adds a "Version" entry. The text has no special internal structure. A doc comment may contain at most one
@version
tag. Version normally refers to the version of the software (such as the JDK) that contains this feature.
@see
classname- Adds a "See Also" entry to the class. Entries for classes and class members will be hyperlinked automatically by javadoc (with some restrictions; see the -linkall option below). Quoted strings can be used for books or other entries that don't have URL references. Some examples are:
@see java.lang.String @see String @see String#equals @see java.lang.Object#wait(int) @see Character#MAX_RADIX @see <a href="spec.html">Java Spec</a> @see "The Java Programming Language"The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name. Whitespace in@see
's classname is significant. If there is more than one argument, there must be a single blank character between the arguments. For example:@see java.io.File#File(java.io.File, java.lang.String)A doc comment may contain more than one
@see
tag.
@since
since-text- Adds a "Since" entry. The text has no special internal structure. This tag means that this change or feature has existed since the release number of the software specified by the since-text (such as the JDK).
@deprecated
deprecated-text- Adds a deprecated 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.
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> * * @author Sami Shaio * @version %I%, %G% * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
A field comment can contain only the@see
,@since
and@deprecated
tags (as described above).An example of a field comment:
/** * The X-coordinate of the window. * * @see window#1 */ int x = 1263732;
Can contain@see
tags, as well as:
@param
parameter-namedescription
- 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-namedescription
- Adds a "Throws" section, which contains the name of the exception that may be thrown by the method. The exception is linked to its class documentation.
@see
classname- Adds a hyperlinked "See Also" entry to the method. This tag is described above.
@since
since-text- See the description above.
@deprecated
deprecated-text- See the description above.
An example of a method doc comment:
/** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue() */ public char charAt(int index) { ... }
The javadoc tool uses doclets to determine its output. If a custom doclet is not specified by using the -doclet option, javadoc uses the default standard doclet. Javadoc provides a set of command-line options that can used with any doclet. These options are described below under the sub-heading Javadoc Options. The standard doclet provides an additional set of command-line options that are described below under the sub-heading Options Provided by the Standard Doclet.Javadoc Options
- -doclet filename
- Specifies class file for the doclet to be used to define the content and format the output. If the
-doclet
option is not used, javadoc uses the standard doclet for API output in the default HTML format.
- -public
- Shows only public classes and members.
- -protected
- Shows only protected and public classes and members. This is the default.
- -package
- Shows only package, protected, and public classes and members.
- -private
- Shows all classes and members.
- -Jflag
- Pass flag directly to the runtime system. For example, if you need to ensure that the system sets aside 32 megabytes of memory to hold the generated documentation, then you would use this flag as follows:
- javadoc -J-mx32m -J-ms32m <classes> ...
- -encoding name
- Specify the source file encoding name, such as
EUCJIS/SJIS
. If this option is not specified, the platform default converter is used.
- -overview path
- Specifies that javadoc should retrieve overview documentation from the file specified by path. Javadoc will take whatever appears between body HTML tags (<body>, </body>) in the overview file, interpret it as HTML, and place it on the package index file (packages.html) beneath the alphabetical list of package links.
- -sourcepath path
- Specifies the search path for source files. Does not affect the loading of class files. The
sourcepath
you specify depends on whether you specify packages or classes as arguments to the javadoc command.When generating documentation for packages, specify
sourcepath
as the directory in the source tree that contains the top-most parent package of the packages you are documenting. The default forsourcepath
is the currentclasspath
directory. For example, suppose you want to document a package calledjava.lang
whose source files are located at:/myapp/src/share/java/lang/*.javaBecausejava
is the top-most parent package, you would specify thesourcepath
to be the directory that containsjava
:-sourcepath /myapp/src/shareWhen generating documentation for discrete classes, specifysourcepath
as the directory in the source tree that contains the classes you are documenting. Note that this is different from thesourcepath
you used when documenting packages. For example, suppose you want to document a class namedjava.lang.String
whose source file is located at:/myapp/src/share/java/lang/String.javaSpecify thesourcepath
to be the directory that contains the classString.java
:-sourcepath /myapp/src/share/java/langYou can omit thesourcepath
option if you first switch to the directory you would have specified.
- -classpath path
- NOTE: In general, do not use -classpath, because it is normally not needed; use -sourcepath instead to specify .java files.
Specifies the directories from which javadoc is to load the.class
files used to execute the javadoc tool. If-sourcepath
is not specified, this also specifies the path javadoc uses to look up the.java
files to document. It overrides the default or the CLASSPATH environment variable, if it is set. The path can contain multiple paths by separating them with a colon. Set the path the same way you do for the CLASSPATH environment variable. For example, the following sets two paths: current directory (.
) and/home/opus/myclasses
:javadoc -classpath .:/home/opus/myclasses myPackage.MyClassThe
-classpath
option is not necessary if you call javadoc wrapper script directly. Normally, if you specifyclasspath
it must precedesourcepath
. However, the order of these two options does not matter if you are using the wrapper script.The value of
classpath
defaults to the current directory plus the classes location, as described in the CLASSPATH environment variable.
Options Provided by the Standard Doclet
- -linkall
- Creates links to API documentation for all classes referred to by the API documents that javadoc is currently generating. For example, suppose javadoc is run, without the -linkall option, on the Graphics.java file in the java.awt package:
javadoc /home/me/java/awt/Graphics.javaThe signature for the Graphics.toString method in the html generated by javadoc will look like this:<pre> public String toString() </pre>No link to the API documentation for class String is generated because class String was not included as input to the javadoc command. If the javadoc command is issued with the -linkall option:javadoc -linkall /home/me/java/awt/Graphics.javaa link to API documentation for the String class is generated:<pre> public <a href="java.lang.String.html#_top_">String</a> toString() </pre>Similar links will be automatically generated for all references to classes not included in the javadoc command. Note that the links are created with the assumption that the linked-to API documenation is in the same directory as the API documentation being generated by javadoc.
- -version
- Include @version tags, which are omitted by default.
- -author
- Include @author tags, which are omitted by default.
- -noindex
- Omit the package index, which is produced by default.
- -notree
- Omit the class/interface hierarchy, which is produced by default.
- -nodeprecatedlist
- Do not generate the file containing the list of deprecated APIs (deprecatedlist.html).
- -nohelp
- Do not generate the HELP link in the navigation bars at the top and bottom of each page of output.
- -helpfile path
- Specifies the path of the help file that the HELP link in the upper and lower navigation bars should link to.
- -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/opus/public_html/doc java.lang- -nodeprecated
- Exclude paragraphs with the @deprecated tag.
- -docencoding name
- Specify output HTML file encoding name.
- -breakindex
- Breaks up the index file into mutliple files, alphabetically, one file per letter, plus a file for any index entries that start with non-alphabetical characters.
- -title title
- Specifies the title to be placed on the package index file. The title will be placed as a centered, level-one heading directly beneath the upper navigation bar. title may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within title may have to be escaped.
- -header header
- Specifies the header to be placed on each output file. The header will be placed on the right edge of the upper navigation bar. header may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within header may have to be escaped.
- -footer footer
- Specifies the footer to be placed on each output file. The footer will be placed on the right edge of the lower navigation bar. footer may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within footer may have to be escaped.
- -bottom text
- Specifies the text to be placed at the bottom of each output file. The text will be placed at the bottom of the page, below the lower navigation bar. text may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within text may have to be escaped.
Each package name has a corresponding directory name. In the following examples, the source files are located at/home/ws/src/java/awt/*java
. The destination directory is/home/ws/html
.Documenting One or More Packages
To document a package, the source files (*.java
) for that package must be located in a directory having the same name as the package. If a package name is made up of several identifiers (separated by dots), each identifier represents a different directory. Thus, all java.awt classes must reside in a directory named java/awt/.First, change to the parent directory of the top-most package (or supply the sourcepath option passing in that directory). Then run javadoc, supplying one or more package names.
% cd /home/ws/src/ % javadoc -d /home/ws/html java.awt java.awt.eventGenerates HTML-formatted documentation for the public classes in packagesjava.awt
andjava.awt.event
and puts it in the specified destination directory (/home/ws/html
).Documenting One or More Classes
Change to the directory holding the class (or supply the sourcepath option with that directory). Then run javadoc, supplying one or more class names.% cd /home/ws/src/java/awt % javadoc -d /home/ws/html Button.java Canvas.javaGenerates HTML-formatted documentation for the two classes.
CLASSPATH
- Provides the system a path to the user-defined classes. Separate directories with a colon, for example,
- .:/home/avh/classes:/usr/local/java/classes
javac, java, jdb, javah, javap, CLASSPATH, Javadoc Home Page