javadoc | The Java Documentation Generator
|
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
|