." Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.

." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

."

." This code is free software; you can redistribute it and/or modify it

." under the terms of the GNU General Public License version 2 only, as

." published by the Free Software Foundation.

."

." This code is distributed in the hope that it will be useful, but WITHOUT

." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

." FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

." version 2 for more details (a copy is included in the LICENSE file that

." accompanied this code).

."

." You should have received a copy of the GNU General Public License version

." 2 along with this work; if not, write to the Free Software Foundation,

." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

."

." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

." or visit www.oracle.com if you need additional information or have any

." questions.

."

.TH javadoc 1 "10 May 2011"

.SH "Name"

javadoc \- The Java API Documentation Generator

.LP

Generates HTML pages of API documentation from Java source files. This document contains Javadoc examples for Solaris.

.SH "SYNOPSIS"

.LP

\f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP

.LP

Arguments can be in any order. See processing of Source Files for details on how the Javadoc tool determines which "\f2.java\fP" files to process.

.RS 3

.TP 3

options

Command\-line options, as specified in this document. To see a typical use of javadoc options, see Real\-World Example.

.TP 3

packagenames

A series of names of packages, separated by spaces, such as \f2java.lang\ java.lang.reflect\ java.awt\fP. You must separately specify each package you want to document. Wildcards are not allowed; use \-subpackages for recursion. The Javadoc tool uses \f2\-sourcepath\fP to look for these package names. See Example \- Documenting One or More Packages

.TP 3

sourcefilenames

A series of source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The Javadoc tool will process every file whose name ends with ".java", and whose name, when stripped of that suffix, is actually a legal class name (see the Java Language Specification). Therefore, you can name files with dashes (such as \f2X\-Buffer\fP), or other illegal characters, to prevent them from being documented. This is useful for test files and template files The path that precedes the source file name determines where javadoc will look for the file. (The Javadoc tool does \f2not\fP use \f2\-sourcepath\fP to look for these source file names.) Relative paths are relative to the current directory, so passing in \f2Button.java\fP is identical to \f2./Button.java\fP. A source file name with an absolute path and a wildcard, for example, is \f2/home/src/java/awt/Graphics*.java\fP. See Example\ \-\ Documenting One or More Classes. You can also mix packagenames and sourcefilenames, as in Example\ \-\ Documenting Both Packages and Classes

.TP 3

\-subpackages pkg1:pkg2:...

Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames.

.TP 3

@argfiles

One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and \f2\-J\fP options are not allowed in these files.

.RE

.SH "DESCRIPTION"

.LP

The \f3Javadoc\fP tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files.

.LP

You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use \f2\-subpackages\fP for traversing recursively down from a top\-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source (\f2.java\fP) filenames. Examples are given at the end of this document. How Javadoc processes source files is covered next.

.SS

Processing of source files

.LP

The Javadoc tool processes files that end in "\f2.java\fP" plus other files described under Source Files. If you run the Javadoc tool by explicitly passing in individual source filenames, you can determine exactly which "\f2.java\fP" files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names. The Javadoc tool can be run three ways without explicitly specifying the source filenames. You can (1) pass in package names, (2) use \f2\-subpackages\fP, and (3) use wildcards with source filenames (\f2*.java\fP). In these cases, the Javadoc tool processes a "\f2.java\fP" file only if it fulfills all of the following requirements:

.RS 3

.TP 2

o

Its name, after stripping off the "\f2.java\fP" suffix, is actually a legal class name (see the Java Language Specification for legal characters)

.TP 2

o

Its directory path relative to the root of the source tree is actually a legal package name (after converting its separators to dots)

.TP 2

o

Its package statement contains the legal package name (specified in the previous bullet)

.RE

.LP

\f3Processing of links\fP \- During a run, the Javadoc tool automatically adds cross\-reference links to package, class and member names that are being documented as part of that run. Links appear in several places:

.RS 3

.TP 2

o

Declarations (return types, argument types, field types)

.TP 2

o

"See Also" sections generated from \f2@see\fP tags

.TP 2

o

In\-line text generated from \f2{@link}\fP tags

.TP 2

o

Exception names generated from \f2@throws\fP tags

.TP 2

o

"Specified by" links to members in interfaces and "Overrides" links to members in classes

.TP 2

o

Summary tables listing packages, classes and members

.TP 2

o

Package and class inheritance trees

.TP 2

o

The index

.RE

.LP

You can add hyperlinks to existing text for classes not included on the command line (but generated separately) by way of the \f2\-link\fP and \f2\-linkoffline\fP options.

.LP

\f3Other processing details\fP \- The Javadoc tool produces one complete document each time it is run; it cannot do incremental builds \-\- that is, it cannot modify or \f2directly\fP incorporate results from previous runs of the Javadoc tool. However, it can link to results from other runs, as just mentioned.

.LP

As implemented, the Javadoc tool requires and relies on the java compiler to do its job. The Javadoc tool calls part of \f2javac\fP to compile the declarations, ignoring the member implementation. It builds a rich internal representation of the classes, including the class hierarchy, and "use" relationships, then generates the HTML from that. The Javadoc tool also picks up user\-supplied documentation from documentation comments in the source code.

.LP

In fact, the Javadoc tool will run on \f2.java\fP source files that are pure stub files with no method bodies. This means you can write documentation comments and run the Javadoc tool in the earliest stages of design while creating the API, before writing the implementation.

.LP

Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code. For example, the Javadoc tool documents default constructors (see Java Language Specification) that are present in the \f2.class\fP files but not in the source code.

.LP

In many cases, the Javadoc tool allows you to generate documentation for source files whose code is incomplete or erroneous. This is a benefit that enables you to generate documentation before all debugging and troubleshooting is done. For example, according to the \f2Java Language Specification\fP, a class that contains an abstract method should itself be declared abstract. The Javadoc tool does not check for this, and would proceed without a warning, whereas the javac compiler stops on this error. The Javadoc tool does do some primitive checking of doc comments. Use the DocCheck doclet to check the doc comments more thoroughly.

.LP

When the Javadoc tool builds its internal structure for the documentation, it loads all referenced classes. Because of this, the Javadoc tool must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes. For more about this, see

.na

\f2How Classes Are Found\fP @

.fi

http://download.oracle.com/javase/7/docs/technotes/tools/findingclasses.html. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path.

.SS

Javadoc Doclets

.LP

You can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built\-in" doclet, called the standard doclet, that generates HTML\-formatted API documentation. You can modify or subclass the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you'd like. Information about doclets and their use is at the following locations:

.RS 3

.TP 2

o

.na

\f2Javadoc Doclets\fP @

.fi

http://download.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html

.TP 2

o

The \f2\-doclet\fP command\-line option

.RE

.LP

When a custom doclet is not specified with the \f2\-doclet\fP command line option, the Javadoc tool will use the default standard doclet. 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.

.SS

Related Documentation and Doclets

.RS 3

.TP 2

o

.na

\f2Javadoc Enhancements\fP @

.fi

http://download.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html for details about improvements added in Javadoc.

.TP 2

o

.na

\f2Javadoc FAQ\fP @

.fi

http://java.sun.com/j2se/javadoc/faq/index.html for answers to common questions, information about Javadoc\-related tools, and workarounds for bugs.

.TP 2

o

.na

\f2How to Write Doc Comments for Javadoc\fP @

.fi

http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html for more information about Sun conventions for writing documentation comments.

.TP 2

o

.na

\f2Requirements for Writing API Specifications\fP @

.fi

http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Standard requirements used when writing the Java SE Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions.

.TP 2

o

.na

\f2Documentation Comment Specification\fP @

.fi

http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html \- The original specification on documentation comments, Chapter 18, Documentation Comments, in the \f2Java Language Specification\fP, First Edition, by James Gosling, Bill Joy, and Guy Steele. (This chapter was removed from the second edition.)

.TP 2

o

.na

\f2DocCheck Doclet\fP @

.fi

http://www.oracle.com/technetwork/java/javase/documentation/index\-141437.html \- Checks doc comments in source files and generates a report listing the errors and irregularities it finds. It is part of the Doc Check Utilities.

.TP 2

o

.na

\f2MIF Doclet\fP @

.fi

http://java.sun.com/j2se/javadoc/mifdoclet/ \- Can automate the generation of API documentation in MIF, FrameMaker and PDF formats. MIF is Adobe FrameMaker's interchange format.

.RE

.SS

Terminology

.LP

The terms \f2documentation comment\fP, \f2doc comment\fP, \f2main description\fP, \f2tag\fP, \f2block tag\fP, and \f2in\-line tag\fP are described at Documentation Comments. These other terms have specific meanings within the context of the Javadoc tool:

.RS 3

.TP 3

generated document

The document generated by the javadoc tool from the doc comments in Java source code. The default generated document is in HTML and is created by the standard doclet.

.LP

.TP 3

name

A name of a program element written in the Java Language \-\- that is, the name of a package, class, interface, field, constructor or method. A name can be fully\-qualified, such as \f2java.lang.String.equals(java.lang.Object)\fP, or partially\-qualified, such as \f2equals(Object)\fP.

.LP

.TP 3

documented classes

The classes and interfaces for which detailed documentation is generated during a javadoc run. To be documented, the source files must be available, their source filenames or package names must be passed into the javadoc command, and they must not be filtered out by their access modifier (public, protected, package\-private or private). We also refer to these as the classes included in the javadoc output, or the \f2included classes\fP.

.LP

.TP 3

included classes

Classes and interfaces whose details are documented during a run of the Javadoc tool. Same as \f2documented classes\fP.

.LP

.TP 3

excluded classes

Classes and interfaces whose details are \f2not\fP documented during a run of the Javadoc tool.

.LP

.TP 3

referenced classes

The classes and interfaces that are explicitly referred to in the definition (implementation) or doc comments of the documented classes and interfaces. Examples of references include return type, parameter type, cast type, extended class, implemented interface, imported classes, classes used in method bodies, @see, {@link}, {@linkplain}, and {@inheritDoc} tags. (Notice this definition has changed since

.na

\f21.3\fP @

.fi

http://download.oracle.com/javase/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses.) When the Javadoc tool is run, it should load into memory all of the referenced classes in javadoc's bootclasspath and classpath. (The Javadoc tool prints a "Class not found" warning for referenced classes not found.) The Javadoc tool can derive enough information from the .class files to determine their existence and the fully\-qualified names of their members.

.LP

.TP 3

external referenced classes

The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are not passed into the Javadoc tool on the command line. Links in the generated documentation to those classes are said to be \f2external references\fP or \f2external links\fP. For example, if you run the Javadoc tool on only the \f2java.awt\fP package, then any class in \f2java.lang\fP, such as \f2Object\fP, is an external referenced class. External referenced classes can be linked to using the \f2\-link\fP and \f2\-linkoffline\fP options. An important property of an external referenced class is that its source comments are normally not available to the Javadoc run. In this case, these comments cannot be inherited.

.RE

.SH "SOURCE FILES"

.LP

The Javadoc tool will generate output originating from four different types of "source" files: Java language source files for classes (\f2.java\fP), package comment files, overview comment files, and miscellaneous unprocessed files. This section also covers test files and template files that can also be in the source tree, but which you want to be sure not to document.

.SS

Class Source Code Files

.LP

Each class or interface and its members can have their own documentation comments, contained in a \f2.java\fP file. For more details about these doc comments, see Documentation Comments.

.SS

Package Comment Files

.LP

Each package can have its own documentation comment, contained in its own "source" file, that the Javadoc tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package.

.LP

To create a package comment file, you have a choice of two files to place your comments:

.RS 3

.TP 2

o

\f2package\-info.java\fP \- Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html.

.TP 2

o

\f2package.html\fP \- Can contain only package comments and Javadoc tags, no package annotations.

.RE

.LP

A package may have a single \f2package.html\fP file or a single \f2package\-info.java\fP file but not both. Place either file in the package directory in the source tree along with your \f2.java\fP files.

.LP

\f4package\-info.java\fP \- This file can contain a package comment of the following structure \-\- the comment is placed before the package declaration:

.LP

File: \f2java/applet/package\-info.java\fP

.nf

\f3

.fl

/**

.fl

 * Provides the classes necessary to create an

.fl

 * applet and the classes an applet uses

.fl

 * to communicate with its applet context.

.fl

 * <p>

.fl

 * The applet framework involves two entities:

.fl

 * the applet and the applet context.

.fl

 * An applet is an embeddable window (see the

.fl

 * {@link java.awt.Panel} class) with a few extra

.fl

 * methods that the applet context can use to

.fl

 * initialize, start, and stop the applet.

.fl

 *

.fl

 * @since 1.0

.fl

 * @see java.awt

.fl

 */

.fl

package java.lang.applet;

.fl

\fP

.fi

.LP

Note that while the comment separators \f2/**\fP and \f2/*\fP must be present, the leading asterisks on the intermediate lines can be omitted.

.LP

\f4package.html\fP \- This file can contain a package comment of the following structure \-\- the comment is placed in the \f2<body>\fP element:

.LP

File: \f2java/applet/package.html\fP

.nf

\f3

.fl

<HTML>

.fl

<BODY>

.fl

Provides the classes necessary to create an applet and the

.fl

classes an applet uses to communicate with its applet context.

.fl

<p>

.fl

The applet framework involves two entities: the applet

.fl

and the applet context. An applet is an embeddable

.fl

window (see the {@link java.awt.Panel} class) with a

.fl

few extra methods that the applet context can use to

.fl

initialize, start, and stop the applet.

.fl

.fl

@since 1.0

.fl

@see java.awt

.fl

</BODY>

.fl

</HTML>

.fl

\fP

.fi

.LP

Notice this is just a normal HTML file and does not include a package declaration. The content of the package comment file is written in HTML, like all other comments, with one exception: The documentation comment should not include the comment separators \f2/**\fP and \f2*/\fP or leading asterisks. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between \f2<body>\fP and the first sentence. You can include package tags; as with any documentation comment, all block tags must appear after the main description. If you add a \f2@see\fP tag in a package comment file, it must have a fully\-qualified name. For more details, see the

.na

\f2example of \fP\f2package.html\fP @

.fi

http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#packagecomments.

.LP

\f3Processing of package comment file\fP \- When the Javadoc tool runs, it will automatically look for the package comment file; if found, the Javadoc tool does the following:

.RS 3

.TP 2

o

Copies the comment for processing. (For \f2package.html\fP, copies all content between \f2<body>\fP and \f2</body>\fP HTML tags. You can include a \f2<head>\fP section to put a \f2<title>\fP, source file copyright statement, or other information, but none of these will appear in the generated documentation.)

.TP 2

o

Processes any package tags that are present.

.TP 2

o

Inserts the processed text at the bottom of the package summary page it generates, as shown in

.na

\f2Package Summary\fP @

.fi

http://download.oracle.com/javase/7/docs/api/java/applet/package\-summary.html.

.TP 2

o

Copies the first sentence of the package comment to the top of the package summary page. It also adds the package name and this first sentence to the list of packages on the overview page, as shown in

.na

\f2Overview Summary\fP @

.fi

http://download.oracle.com/javase/7/docs/api/overview\-summary.html. The end\-of\-sentence is determined by the same rules used for the end of the first sentence of class and member main descriptions.

.RE

.SS

Overview Comment File

.LP

Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the Javadoc tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.

.LP

To create an overview comment file, you can name the file anything you want, typically \f4overview.html\fP and place it anywhere, typically at the top level of the source tree. For example, if the source files for the \f2java.applet\fP package are contained in \f2/home/user/src/java/applet\fP directory, you could create an overview comment file at \f2/home/user/src/overview.html\fP.

.LP

Notice you can have multiple overview comment files for the same set of source files, in case you want to run javadoc multiple times on different sets of packages. For example, you could run javadoc once with \-private for internal documentation and again without that option for public documentation. In this case, you could describe the documentation as public or internal in the first sentence of each overview comment file.

.LP

The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. See that description for details. To re\-iterate, when writing the comment, you should make the first sentence a summary about the application or set of packages, and not put a title or any other text between \f2<body>\fP and the first sentence. You can include overview tags; as with any documentation comment, all tags except in\-line tags, such as \f2{@link}\fP, must appear after the main description. If you add a \f2@see\fP tag, it must have a fully\-qualified name.

.LP

When you run the Javadoc tool, you specify the overview comment file name with the \-overview option. The file is then processed similar to that of a package comment file.

.RS 3

.TP 2

o

Copies all content between \f2<body>\fP and \f2</body>\fP tags for processing.

.TP 2

o

Processes any overview tags that are present.

.TP 2

o

Inserts the processed text at the bottom of the overview page it generates, as shown in

.na

\f2Overview Summary\fP @

.fi

http://download.oracle.com/javase/7/docs/api/overview\-summary.html.

.TP 2

o

Copies the first sentence of the overview comment to the top of the overview summary page.

.RE

.SS

Miscellaneous Unprocessed Files

.LP

You can also include in your source any miscellaneous files that you want the Javadoc tool to copy to the destination directory. These typically includes graphic files, example Java source (.java) and class (.class) files, and self\-standing HTML files whose content would overwhelm the documentation comment of a normal Java source file.

.LP

To include unprocessed files, put them in a directory called \f4doc\-files\fP which can be a subdirectory of any package directory that contains source files. You can have one such subdirectory for each package. You might include images, example code, source files, .class files, applets and HTML files. For example, if you want to include the image of a button \f2button.gif\fP in the \f2java.awt.Button\fP class documentation, you place that file in the \f2/home/user/src/java/awt/doc\-files/\fP directory. Notice the \f2doc\-files\fP directory should not be located at \f2/home/user/src/java/doc\-files\fP because \f2java\fP is not a package \-\- that is, it does not directly contain any source files.

.LP

All links to these unprocessed files must be hard\-coded, because the Javadoc tool does not look at the files \-\- it simply copies the directory and all its contents to the destination. For example, the link in the \f2Button.java\fP doc comment might look like:

.nf

\f3

.fl

    /**

.fl

     * This button looks like this:

.fl

     * <img src="doc\-files/Button.gif">

.fl

     */

.fl

\fP

.fi

.SS

Test Files and Template Files

.LP

Some developers have indicated they want to store test files and templates files in the source tree near their corresponding source files. That is, they would like to put them in the same directory, or a subdirectory, of those source files.

.LP

If you run the Javadoc tool by explicitly passing in individual source filenames, you can deliberately omit test and templates files and prevent them from being processed. However, if you are passing in package names or wildcards, you need to follow certain rules to ensure these test files and templates files are not processed.

.LP

Test files differ from template files in that the former are legal, compilable source files, while the latter are not, but may end with ".java".

.LP

\f3Test files\fP \- Often developers want to put compilable, runnable test files for a given package in the \f2same\fP directory as the source files for that package. But they want the test files to belong to a package other than the source file package, such as the unnamed package (so the test files have no package statement or a different package statement from the source). In this scenario, when the source is being documented by specifying its package name specified on the command line, the test files will cause warnings or errors. You need to put such test files in a subdirectory. For example, if you want to add test files for source files in \f2com.package1\fP, put them in a subdirectory that would be an invalid package name (because it contains a hyphen):

.nf

\f3

.fl

    com/package1/test\-files/

.fl

\fP

.fi

.LP

The test directory will be skipped by the Javadoc tool with no warnings.

.LP

If your test files contain doc comments, you can set up a separate run of the Javadoc tool to produce documentation of the test files by passing in their test source filenames with wildcards, such as \f2com/package1/test\-files/*.java\fP.

.LP

\f3Templates for source files\fP \- Template files have names that often end in ".java" and are not compilable. If you have a template for a source file that you want to keep in the source directory, you can name it with a dash (such as \f2Buffer\-Template.java\fP), or any other illegal Java character, to prevent it from being processed. This relies on the fact that the Javadoc tool will only process source files whose name, when stripped of the ".java" suffix, is actually a legal class name (see information about Identifiers in the Java Language Specification).

.SH "GENERATED FILES"

.LP

By default, javadoc uses a standard doclet that generates HTML\-formatted documentation. This doclet generates the following kinds of files (where each HTML "page" corresponds to a separate file). Note that javadoc generates files with two types of names: those named after classes/interfaces, and those that are not (such as \f2package\-summary.html\fP). Files in the latter group contain hyphens to prevent filename conflicts with those in the former group.

.LP

\f3Basic Content Pages\fP

.RS 3

.TP 2

o

One \f3class or interface page\fP (\f2classname\fP\f2.html\fP) for each class or interface it is documenting.

.TP 2

o

One \f3package page\fP (\f2package\-summary.html\fP) for each package it is documenting. The Javadoc tool will include any HTML text provided in a file named \f2package.html\fP or \f2package\-info.java\fP in the package directory of the source tree.

.TP 2

o

One \f3overview page\fP (\f2overview\-summary.html\fP) for the entire set of packages. This is the front page of the generated document. The Javadoc tool will include any HTML text provided in a file specified with the \f2\-overview\fP option. Note that this file is created only if you pass into javadoc two or more package names. For further explanation, see HTML Frames.)

.RE

.LP

\f3Cross\-Reference Pages\fP

.RS 3

.TP 2

o

One \f3class hierarchy page for the entire set of packages\fP (\f2overview\-tree.html\fP). To view this, click on "Overview" in the navigation bar, then click on "Tree".

.TP 2

o

One \f3class hierarchy page for each package\fP (\f2package\-tree.html\fP) To view this, go to a particular package, class or interface page; click "Tree" to display the hierarchy for that package.

.TP 2

o

One \f3"use" page\fP for each package (\f2package\-use.html\fP) and a separate one for each class and interface (\f2class\-use/\fP\f2classname\fP\f2.html\fP). This page describes what packages, classes, methods, constructors and fields use any part of the given class, interface or package. Given a class or interface A, its "use" page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

.TP 2

o

A \f3deprecated API page\fP (\f2deprecated\-list.html\fP) listing all deprecated names. (A deprecated name is not recommended for use, generally due to improvements, and a replacement name is usually given. Deprecated APIs may be removed in future implementations.)

.TP 2

o

A \f3constant field values page\fP (\f2constant\-values.html\fP) for the values of static fields.

.TP 2

o

A \f3serialized form page\fP (\f2serialized\-form.html\fP) for information about serializable and externalizable classes. Each such class has a description of its serialization fields and methods. This information is of interest to re\-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class comment. The standard doclet automatically generates a serialized form page: any class (public or non\-public) that implements Serializable is included, along with \f2readObject\fP and \f2writeObject\fP methods, the fields that are serialized, and the doc comments from the \f2@serial\fP, \f2@serialField\fP, and \f2@serialData\fP tags. Public serializable classes can be excluded by marking them (or their package) with \f2@serial exclude\fP, and package\-private serializable classes can be included by marking them (or their package) with \f2@serial include\fP. As of 1.4, you can generate the complete serialized form for public and private classes by running javadoc \f2without\fP specifying the \f2\-private\fP option.

.TP 2

o

An \f3index\fP (\f2index\-*.html\fP) of all class, interface, constructor, field and method names, alphabetically arranged. This is internationalized for Unicode and can be generated as a single file or as a separate file for each starting character (such as A\-Z for English).

.RE

.LP

\f3Support Files\fP

.RS 3

.TP 2

o

A \f3help page\fP (\f2help\-doc.html\fP) that describes the navigation bar and the above pages. You can provide your own custom help file to override the default using \f2\-helpfile\fP.

.TP 2

o

One \f3index.html file\fP which creates the HTML frames for display. This is the file you load to display the front page with frames. This file itself contains no text content.

.TP 2

o

Several \f3frame files\fP (\f2*\-frame.html\fP) containing lists of packages, classes and interfaces, used when HTML frames are being displayed.

.TP 2

o

A \f3package list\fP file (\f2package\-list\fP), used by the \f2\-link\fP and \f2\-linkoffline\fP options. This is a text file, not HTML, and is not reachable through any links.

.TP 2

o

A \f3style sheet\fP file (\f2stylesheet.css\fP) that controls a limited amount of color, font family, font size, font style and positioning on the generated pages.

.TP 2

o

A \f3doc\-files\fP directory that holds any image, example, source code or other files that you want copied to the destination directory. These files are not processed by the Javadoc tool in any manner \-\- that is, any javadoc tags in them will be ignored. This directory is not generated unless it exists in the source tree.

.RE

.LP

\f3HTML Frames\fP

.LP

The Javadoc tool will generate either two or three HTML frames, as shown in the figure below. It creates the minimum necessary number of frames by omitting the list of packages if there is only one package (or no packages). That is, when you pass a single package name or source files (*.java) belonging to a single package as arguments into the javadoc command, it will create only one frame (C) in the left\-hand column \-\- the list of classes. When you pass into javadoc two or more package names, it creates a third frame (P) listing all packages, as well as an overview page (Detail). This overview page has the filename \f2overview\-summary.html\fP. Thus, this file is created only if you pass in two or more package names. You can bypass frames by clicking on the "No Frames" link or entering at overview\-summary.html.

.LP

If you are unfamiliar with HTML frames, you should be aware that frames can have \f2focus\fP for printing and scrolling. To give a frame focus, click on it. Then on many browsers the arrow keys and page keys will scroll that frame, and the print menu command will print it.

.LP

Load one of the following two files as the starting page depending on whether you want HTML frames or not:

.RS 3

.TP 2

o

\f2index.html\fP (for frames)

.TP 2

o

\f2overview\-summary.html\fP (for no frames)

.RE

.LP

\f3Generated File Structure\fP

.LP

The generated class and interface files are organized in the same directory hierarchy that Java source files and class files are organized. This structure is one directory per subpackage.

.LP

For example, the document generated for the class \f2java.applet.Applet\fP class would be located at \f2java/applet/Applet.html\fP. The file structure for the java.applet package follows, given that the destination directory is named \f2apidocs\fP. All files that contain the word "frame" appear in the upper\-left or lower\-left frames, as noted. All other HTML files appear in the right\-hand frame.

.LP

NOTE \- Directories are shown in \f3bold\fP. The asterisks (\f2*\fP) indicate the files and directories that are \f2omitted\fP when the arguments to javadoc are source filenames (*.java) rather than package names. Also when arguments are source filenames, \f2package\-list\fP is created but is empty. The doc\-files directory will not be created in the destination unless it exists in the source tree.

.nf

\f3

.fl

.fl

\fP\f3apidocs\fP                             Top directory

.fl

   index.html                       Initial page that sets up HTML frames

.fl

 * overview\-summary.html            Lists all packages with first sentence summaries

.fl

   overview\-tree.html               Lists class hierarchy for all packages

.fl

   deprecated\-list.html             Lists deprecated API for all packages

.fl

   constant\-values.html             Lists values of static fields for all packages

.fl

   serialized\-form.html             Lists serialized form for all packages