Synopsis

javadoc [ options ] @list package... sourcefiles...

Description

javadoc generates API documentation for any number of packages and classes you specify. The javadoc command line can list any number of package names and any number of Java source files. For convenience, when working with a large number of command-line options, or a large number of package or class names, you can place them all in an auxiliary file and specify the name of that file on the command line, preceded by an @ character.

javadoc uses the javac compiler to process all the specified Java source files and all the Java source files in all the specified packages. It uses the information it gleans from this processing to generate detailed API documentation. Most importantly, the generated documentation includes the contents of all documentation comments included in the source files. See Chapter 7 for information about writing doc comments in your own Java code.

When you specify a Java source file for javadoc to process, you must specify the name of the file that contains the source, including a complete path to the file. It is more common, however, to use javadoc to create documentation for entire packages of classes. When you specify a package for javadoc to process, you specify the package name, not the directory that contains the source code for the package. In this case, you may need to specify the -sourcepath option so that javadoc can find your package source code correctly if it is not stored in a location already listed in your default classpath.

javadoc creates HTML documentation by default, but you can customize its behavior by defining a doclet class that generates documentation in whatever format you desire. You can write your own doclets using the doclet API defined by the com.sun.javadoc package. Documentation for this package is included in the standard documentation bundle for Java 1.2 and later.

javadoc gained significant new functionality in Java 1.2. Here we document Java 1.2 and later versions of the program and do not distinguish these features from those in previous versions.

Options

javadoc defines a large number of options. Some are standard options that are always recognized by javadoc. Other options are defined by the doclet that produces the documentation. The options for the standard HTML doclet are included in the following list:

-1.1

Simulates the output style and directory structure of the Java 1.1 version of javadoc. This option existed in Java 1.2 and 1.3 and was removed in Java 1.4.

-author

Includes authorship information specified with @author in the generated documentation. Default doclet only.

-bootclasspath

Specifies the location of an alternate set of system classes. This can be useful when cross-compiling. See javac for more information on this option.

-bottom text

Displays text at the bottom of each generated HTML file. text can contain HTML tags. See also -footer. Default doclet only.

-breakiterator

Uses the java.text.BreakIterator algorithm for determining the end of the summary sentence in doc comments. Default doclet only.

-charset encoding

Specifies the character encoding for the output. This depends on the encoding used in the documentation comments of your source code, of course. The encoding value is used in a <meta> tag in the HTML output. Default doclet only.

-classpath path

Specifies a path javadoc uses to look up both class files and, if you do not specify the -sourcepath option, source files. Because javadoc uses the javac compiler, it needs to be able to locate class files for all classes referenced by the packages being documented. See java and javac for more information about this option and the default value provided by the CLASSPATH environment variable.

-d directory

Specifies the directory in and beneath which javadoc should store the HTML files it generates. If this option is omitted, the current directory is used. Default doclet only.

-docencoding encoding

Specifies the encoding to be used for output HTML documents. The name of the encoding specified here may not exactly match the name of the charset specified with the -charset option. Default doclet only.

-docfilessubdirs

Recursively copies any subdirectories of a doc-files directory instead of simply copying the files contained directly within doc-files. Default doclet only.

-doclet classname

Specifies the name of the doclet class to use to generate the documentation. If this option is not specified, javadoc generates documentation using the default HTML doclet.

-docletpath classpath

Specifies a path from which the class specified by the -doclet tag can be loaded if it is not available from the default classpath.

-doctitle text

Provides a title to display at the top of the documentation overview file. This file is often the first thing readers see when they browse the generated documentation. The title can contain HTML tags. Default doclet only.

-encoding encoding-name

Specifies the character encoding of the input source files and the documentation comments they contain. This can be different from the desired output encoding specified by -docencoding. The default is the platform default encoding.

-exclude packages

Excludes the named packages from the set of packages defined by a -subpackages option. packages is a colon-separated list of package names. Default doclet only.

-excludedocfilessubdir dirs

Excludes specified subdirectories of a doc-files directory when -docfilessubdirs is specified. This is useful for excluding version control directories, for example. dirs is a colon-separated list of directory names relative to the doc-files directory. Default doclet only.

-extdirs dirlist

Specifies a list of directories to search for standard extensions. Only necessary when cross-compiling with -bootclasspath. See javac for details.

-footer text

Specifies text to be displayed near the bottom of each file to the right of the navigation bar. text can contain HTML tags. See also -bottom and -header. Default doclet only.

-group title packagelist

javadoc generates a top-level overview page that lists all packages in the generated document. By default, these packages are listed in alphabetical order in a single table. You can break them into groups of related packages with this option, however. The title specifies the title of the package group, such as "Core Packages." The packagelist is a colon-separated list of package names, each of which can include a trailing * character as a wildcard. The javadoc command line can contain any number of -group options. For example:

% javadoc -group "AWT Packages" java.awt* \
-group "Swing Packages" javax.accessibility:javax.swing*

-header text

Specifies text to be displayed near the top of file, to the right of the upper navigation bar. text can contain HTML tags. See also -footer, -doctitle, and -windowtitle. Default doclet only.

-help

Displays a usage message for javadoc.

-helpfile file

Specifies the name of an HTML file that contains help for using the generated documentation. javadoc includes links to this help file in all files it generates. If this option is not specified, javadoc creates a default help file. Default doclet only.

-J javaoption

Passes the argument javaoption directly through to the Java interpreter. When processing a large number of packages, you may need to use this option to increase the amount of memory javadoc is allowed to use. For example:

% javadoc -J-Xmx64m

Note that because -J options are passed directly to the Java interpreter before javadoc starts up, they cannot be included in an external file specified on the command line with the @list syntax.

-keywords

Tells javadoc to include type and member names in <Meta> tag keyword lists. Default doclet only.

-link url

Specifies an absolute or relative URL of the top-level directory of another javadoc-generated document. javadoc uses this URL as the base URL for links from the current document to packages, classes, methods, and fields that are not documented in the current document. For example, when using javadoc to produce documentation for your own packages, you can use this option to link your documentation to the javadoc documentation for the core Java APIs. Default doclet only.

The directory specified by url must contain a file named package-list, and javadoc must be able to read this file at runtime. This file is automatically generated by a previous run of javadoc; it contains a list of all packages documented at the url.

More than one -link option can be specified, although this does not work properly in early releases of Java 1.2. If no -link option is specified, references in the generated documentation to classes and members that are external to the documentation are not hyperlinked.

-linkoffline url packagelist

Similar to the -link option, except that the packagelist file is explicitly specified on the command line. This is useful when the directory specified by url does not have a package-list file or when that file is not available when javadoc is run. Default doclet only.

-linksource

Creates an HTML version of each source file read and includes links to it from the documentation pages. Default doclet only.

-locale language_country_variant

Specifies the locale to use for generated documentation. This is used to look up a resource file that contains localized messages and text for the output files.

-nocomment

Ignores all doc comments and generates documentation that includes only raw API information without any accompanying prose. Default doclet only.

-nodeprecated

Tells javadoc to omit documentation for deprecated features. This option implies -nodeprecatedlist. Default doclet only.

-nodeprecatedlist

Tells javadoc not to generate the deprecated-list.html file and not to output a link to it on the navigation bar. Default doclet only.

-nohelp

Tells javadoc not to generate a help file or a link to it in the navigation bar. Default doclet only.

-noindex

Tells javadoc not to generate index files. Default doclet only.

-nonavbar

Tells javadoc to omit the navigation bars from the top and bottom of every file. Also omits the text specified by -header and -footer. This is useful when generating documentation to be printed. Default doclet only.

-noqualifier packages | all

javadoc omits package names in its generated documentation for classes in the same package being documented. This option tells it to additionally omit package names for classes in the specified packages, or, if the all keyword is used, in all packages. packages is a colon-separated list of package names, which may include the * wildcard to indicate subpackages. For example, -noqualifier java.io:java.nio.* would exclude package names for all classes in the java.io package and in java.nio and its subpackages. Default doclet only.

-nosince

Ignores @since tags in doc comments. Default doclet only.

-notimestamp

Don't output timestamps in HTML comments. Default doclet only.

-notree

Tells javadoc not to generate the tree.html class hierarchy diagram or a link to it in the navigation bar. Default doclet only.

-overview filename

Reads an overview doc comment from filename and uses that comment in the overview page. This file does not contain Java source code, so the doc comment should not actually appear between /** and */ delimiters.

-package

Includes package-visible classes and members in the output, as well as public and protected classes and members.

-private

Includes all classes and members, including private and package-visible classes and members, in the generated documentation.

-protected

Includes public and protected classes and members in the generated output. This is the default.

-public

Includes only public classes and members in the generated output. Omits protected, private, and package-visible classes and members.

-quiet

Suppresses output except warnings and error messages.

-serialwarn

Issues warnings about serializable classes that do not adequately document their serialization format with @serial and related doc-comment tags. Default doclet only.

-source release

Specifies the release of Java for which the source files were written. See the -source option of javac. Legal values are 5, 1.5, 1.4, and 1.3. The options 1.5 and 5 are synonyms and are the default.

-sourcepath path

Specifies a search path for source files, typically set to a single root directory. javadoc uses this path when looking for the Java source files that implement a specified package.

-splitindex

Generates multiple index files, one for each letter of the alphabet. Use this option when documenting large amounts of code. Otherwise, the single index file generated by javadoc will be too large to be useful. Default doclet only.

-stylesheetfile file

Specifies a file to use as a CSS stylesheet for the generated HTML. javadoc inserts appropriate links to this file in the generated documentation. Default doclet only.

-subpackages packages

Specifies that javadoc should process the specified packages and all of their subpackages. packages is a colon-separated list of package names or package name prefixes. Using this option is often easier than explicitly listing all desired package names. For example:

-subpackages java:javax

See also -exclude. Default doclet only.

-tag tagname:where:header-text

Specifies that javadoc should handle a doc-comment tag named tagname by outputting the text header-text followed by whatever text follows the tag. This enables the use of simple custom tags (with the same syntax as @return and @author) in doc comments. where is a string of characters that specifies the types of doc comments in which this custom tag is allowed. The characters and their meanings are a (all: valid everywhere), p (packages), t (types: classes and interfaces), c (constructors), m (methods), and f (fields).

A secondary purpose of the -tag option is to specify the order in which tags are processed and in which their output appears. You can include the names of standard tags after the -tag option to specify this ordering. Custom tags and taglets can be included within this list of standard -tag options. Default doclet only.

-taglet classname

Specifies the classname of a "taglet" class to process a custom tag. Writing taglets is not covered here. -taglet tags may be interspersed with -tag tags to specify the order in which tags should be processed and output. Default doclet only.

-tagletpath classpath

Specifies a colon-separated list of JAR files or directories that form the classpath to be searched for taglet classes. Default doclet only.

-use

Generates and inserts links to an additional file for each class and package that lists the uses of the class or package.

-verbose

Displays additional messages while processing source files.

-version

Includes information from @version tags in the generated output. This option does not tell javadoc to print its own version number. Default doclet only.

-windowtitle text

Specifies text to be output in the <Title> tag of each generated file. This title typically appears as the title of the web browser window and in history and bookmark lists. text should not contain HTML tags. See also -doctitle and -header. Default doclet only.

Environment

CLASSPATH

This environment variable specifies the default classpath javadoc uses to find the class files and source files. It is overridden by the -classpath and -sourcepath options. See java and javac for further discussion of the classpath.

See also

java, javac