.'" t

."

." Copyright 2000-2006 Sun Microsystems, Inc.  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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

." CA 95054 USA or visit www.sun.com if you need additional information or

." have any questions.

."

." `

.TH javadoc 1 "07 Aug 2006"

." Generated by html2man

.SH NAME

javadoc \- The Java API Documentation Generator

.RS 3

.LP

.LP

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

.LP

.RE

.SH "SYNOPSIS"

.LP

.LP

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

.LP

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

.LP

.RS 3

.LP

.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 

.na

\f2Identifiers\fP @

.fi

http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625). 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

.LP

.RE

.SH "DESCRIPTION"

.LP

.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

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

.LP

.SS 

Processing of source files

.LP

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

.LP

.RS 3

.TP 2

o

Its name, after stripping off the "\f2.java\fP" suffix, is actually a legal class name (see 

.na

\f2Identifiers\fP @

.fi

http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625 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

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

.LP

.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

.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

.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

.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

.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

.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 

.na

\f2default constructors\fP @

.fi

http://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154 (section 8.6.7 of \f2Java Language Specification\fP) that are present in the \f2.class\fP files but not in the source code.

.LP

.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

.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 How Classes Are Found. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path.

.LP

.SS 

Javadoc Doclets

.LP

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

.LP

.RS 3

.TP 2

o

Javadoc Doclets 

.TP 2

o

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

.RE

.LP

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

.LP

.SS 

Related Documentation and Doclets

.LP

.RS 3

.TP 2

o

Javadoc Enhancements 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://java.sun.com/j2se/javadoc/writingdoccomments/index.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 2 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://java.sun.com/javadoc/doccheck \- Checks doc comments in source files and generates a report listing the errors and irregularities it finds. It is part of the Sun Doc Check Utilities. 

.TP 2

o

.na

\f2MIF Doclet\fP @

.fi

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

.RE

.LP

.SS 

Terminology

.LP

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

.LP

.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://java.sun.com/j2se/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

.LP

.SH "SOURCE FILES"

.LP

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

.LP

.SS 

Class Source Code Files

.LP

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

.LP

.SS 

Package Comment Files

.LP

.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

.LP

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

.LP

.RS 3

.TP 2

o

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

.TP 2

o

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

.RE

.LP

.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

.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

.LP

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

.LP

.LP

.TS

.if \n+(b.=1 .nr d. \n(.c-\n(c.-1

.de 35

.ps \n(.s

.vs \n(.vu

.in \n(.iu

.if \n(.u .fi

.if \n(.j .ad

.if \n(.j=0 .na

..

.nf

.nr #~ 0

.if n .nr #~ 0.6n

.ds #d .d

.if \(ts\n(.z\(ts\(ts .ds #d nl

.fc

.nr 33 \n(.s

.rm 80

.nr 34 \n(.lu

.eo

.am 80

.br

.di a+

.35

.ft \n(.f

.ll \n(34u*1u/2u

.if \n(.l<\n(80 .ll \n(80u

.in 0

.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

.br

.di

.nr a| \n(dn

.nr a- \n(dl

..

.ec \

.35

.nf

.ll \n(34u

.nr 80 0

.80

.rm 80

.nr 38 \n(a-

.if \n(80<\n(38 .nr 80 \n(38

.35

.nf

.ll \n(34u

.nr 38 1n

.nr 79 0

.nr 40 \n(79+(0*\n(38)

.nr 80 +\n(40

.nr TW \n(80

.if t .if \n(TW>\n(.li .tm Table at line 326 file Input is too wide - \n(TW units

.fc  

.nr #T 0-1

.nr #a 0-1

.eo

.de T#

.ds #d .d

.if \(ts\n(.z\(ts\(ts .ds #d nl

.mk ##

.nr ## -1v

.ls 1

.ls

..

.ec

.ne \n(a|u+\n(.Vu

.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)

.ta \n(80u 

.nr 31 \n(.f

.nr 35 1m

\&\h'|\n(40u'

.mk ##

.nr 31 \n(##

.sp |\n(##u-1v

.nr 37 \n(40u

.in +\n(37u

.a+

.in -\n(37u

.mk 32

.if \n(32>\n(31 .nr 31 \n(32

.sp |\n(31u

.fc

.nr T. 1

.T# 1

.35

.rm a+

.TE

.if \n-(b.=0 .nr c. \n(.c-\n(d.-42

.LP

.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

.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

.LP

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

.LP

.LP

.TS

.if \n+(b.=1 .nr d. \n(.c-\n(c.-1

.de 35

.ps \n(.s

.vs \n(.vu

.in \n(.iu

.if \n(.u .fi

.if \n(.j .ad

.if \n(.j=0 .na

..

.nf

.nr #~ 0

.if n .nr #~ 0.6n

.ds #d .d

.if \(ts\n(.z\(ts\(ts .ds #d nl

.fc

.nr 33 \n(.s

.rm 80

.nr 34 \n(.lu

.eo

.am 80

.br

.di a+

.35

.ft \n(.f

.ll \n(34u*1u/2u

.if \n(.l<\n(80 .ll \n(80u

.in 0

.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

.br

.di

.nr a| \n(dn

.nr a- \n(dl

..

.ec \

.35

.nf

.ll \n(34u

.nr 80 0

.80

.rm 80

.nr 38 \n(a-

.if \n(80<\n(38 .nr 80 \n(38

.35

.nf

.ll \n(34u

.nr 38 1n

.nr 79 0

.nr 40 \n(79+(0*\n(38)

.nr 80 +\n(40

.nr TW \n(80

.if t .if \n(TW>\n(.li .tm Table at line 379 file Input is too wide - \n(TW units

.fc  

.nr #T 0-1

.nr #a 0-1

.eo