home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Java in a Nutshell

Previous Chapter 16
JDK Tools
Next
 

javadoc

Name

javadoc---The Java Documentation Generator

Availability

JDK 1.0 and later.

Synopsis

javadoc [ options ] packagename
javadoc [ options ] filenames

Description

javadoc generates API documentation, in HTML format, for the specified package, or for the individual Java source files specified on the command line.

When a package name is specified on the command line, javadoc looks for a corresponding package directory relative to the class path. It then parses all of the .java source files in that directory and generates an HTML documentation file for each class and an HTML index of the classes in the package. By default, the HTML files are placed in the current directory. The -d option allows you to override this default.

Note that the packagename argument to javadoc is the name of the package (components separated by periods) and not the name of the package directory. You may need to specify the -sourcepath option so that javadoc can find your package source code correctly, if it is not stored in the same location as the package class files.

javadoc may also be invoked with any number of Java source files specified on the command line. Note that these are filenames, not class names, and are specified with any necessary directory components, and with the .java extension. When javadoc is invoked in this way, it reads the specified source files and generates HTML files (in the current directory, by default) that describe each public class defined in the specified source files.

The class documentation files that javadoc generates describe the class (or interface) and its inheritance hierarchy, and index and describe each of the public and protected members of the class. The generated file also contains any "doc comments" that are associated with the class and with its methods, constructors, and variables. A "doc comment," or documentation comment, is a Java comment that begins with /** and ends with */. A doc comment may include any HTML markup tags (although it should not include structuring tags like <H1> or <HR>), and may also include tag values that are treated specially by javadoc. These special tags and their syntax are documented fully in Chapter 13, Java Syntax.

Options

-author path

Specifies that author information specified with the @author tag should be output. This information is not output by default.

-classpath path

This option specifies a path that javadoc uses to look up both class files and source files for the specified package. If you specify this option to tell javadoc to look for your source files, you must also be sure to include the standard system classpath as well, or javadoc will not be able to find the classes it needs. This option overrides the default path and any path specified by the CLASSPATH environment variable. The path specified is an ordered list of directories and ZIP files, separated by colons on UNIX systems or semicolons on Windows systems. To specify additional directories or ZIP files to search without overriding the default system class path, use the CLASSPATH environment variable. See the java reference page for more information on specifying paths.

-d directory

The directory in which javadoc should store the HTML files it generates. The default is the current directory.

-docencoding encoding-name

Specifies the character encoding to be used for the output documents generated by javadoc. Available in JDK 1.1 and later.

-encoding encoding-name

Specifies the character encoding to be used to read the input source files and the documentation comments they contain. Available in JDK 1.1 and later.

-Jjavaoption

Pass the argument javaoption directly through to the Java interpreter. javaoption should not contain spaces; if multiple arguments must be passed to the interpreter, use multiple -J options. Available in JDK 1.1 and later.

-nodeprecated

Specifies that javadoc should not include @deprecated tags in its output, as it does by default. Available in JDK 1.1 and later.

-noindex

Specifies that javadoc should not generate the AllNames.html index file that it creates by default.

-notree

Specifies that javadoc should not generate the tree.html class hierarchy file that it creates by default.

-sourcepath path

A synonym for -classpath. Note that any specified "sourcepath" must include the system classpath.

-verbose

Tells javadoc to print additional messages about what it is doing.

-version path

Specifies that version information specified with the @version tag should be output. This information is not output by default. Note that this option does not tell javadoc to print its own version number.

Environment

CLASSPATH

Specifies an ordered list (colon-separated on UNIX, semicolon-separated on Windows systems) of directories and ZIP files in which javadoc should look for class definitions. When a path is specified with this environment variable, javadoc always implicitly appends the location of the system classes to the end of the path. If this environment variable is not specified, then the default path is the current directory and the system classes. This variable is overridden by the -classpath option.

Bugs

When javadoc cannot find a specified package, it produces a stub HTML file and does not warn you that the package was not found.

See Also

java, javac


Previous Home Next
javac Book Index javah

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java