[Chapter 16] javadoc

#

| Chapter 16 JDK Tools |

# 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.

`-J`javaoption

  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

javac |  | javah