Партнёры:
Хостинг:
NAME
javadoc - Java API Documentation Generator
SYNOPSIS
javadoc [ -author ] [ -classpath path ] [ -d directory ]
[ -d ] [ -docencoding name ] [ -encoding name ]
[ -J flag ] [ -nodeprecated ] [ -noindex ] [ -notree ]
[ -package ] [ -private ] [ -protected ] [ -public ]
[ -sourcepath path ] [ -verbose ] [ -version ]
[ package | source.java ]*
DESCRIPTION
The javadoc command parses the declarations and documenta-
tion comments in a set of Java source files and produces a
set of HTML pages describing, by default, the public and
protected classes, interfaces, constructors, methods, and
fields. As an argument to javadoc you pass either a series
of Java package names or source files.
javadoc generates one .html file for each .java file and
each package it encounters. In addition, it produces a class
hierarchy (tree.html) and an index of those members
(AllNames.html).
When javadoc parses the class and member delarations, it
picks up their signatures for inclusion. Further documenta-
tion can be added by including doc comments in the source
code.
Commenting the Source Code
You can include documentation comments in the source code. A
doc comment consists of the characters between the /** that
begins the comment and the */ that ends it. The text is
divided into one or more lines. When javadoc parses a doc
comment, leading * characters on each line are discarded;
for lines other than the first, blanks and tabs preceding
the initial * characters are also discarded. These comments
may include HTML tags. Here is a doc comment:
/**
* This is a <b>doc</b> comment.
*/
The first sentence of each doc comment should be a summary
sentence, containing a concise but complete description of
the declared entity. This sentence ends at the first period
that is followed by a blank, tab, or line terminator, or at
the first tag (as defined below). javadoc copies this first
sentence to the member summary at the top of the .html file.
Documentation comments are only recognized when placed
immediately before class, interface, constructor, method, or
field declarations.
When you embed HTML tags within a doc comment, you should
not use heading tags such as <h1> and <h2> because javadoc
creates an entire structured document and these structural
tags interfere with the formatting of the generated docu-
ment.
For the specification on documentation comments, see Chapter
18, "Documentation Comments," in The Java Language Specifi-
cation, by James Gosling, Bill Joy, and Guy Steele. (See
SEE ALSO section below.)
Tagged Paragraphs
javadoc parses special tags that are recognized when they
are embedded within a Java doc comment. These doc tags
enable you to autogenerate a complete, well-formatted API
from your source code. The tags start with an "at" sign ( @
).
Tags must start at the beginning of a line. Keep tags with
the same name together within a doc comment. For example,
put all @author tags together so that javadoc can tell where
the list ends.
The tags fall into three categories: class and interface
tags, field tags, and constructor and method tags; each is
itemized in the following sections.
Class and Interface Documentation Tags
@author name-text
Creates an "Author" entry. The text has no
special internal structure. A doc comment may
contain multiple @author tags.
@deprecated deprecated-text
Adds a deprecated comment indicating that
this API should no longer be used (even
though it may continue to work). The conven-
tion is to describe the API that serves as a
replacement. For example:
@deprecated Replaced by setBounds(int,
int, int,
If the member is obsolete and there is no
replacement, the argument to @deprecated
should be "No replacement".
For more about this tag, see Deprecation of
APIs.
@version version-text
Adds a "Version" entry. The text has no spe-
cial internal structure. A doc comment may
contain, at most, one @version tag. Version
normally refers to the version of the
software (such as the JDK) that contains this
feature.
@since since-text
Adds a "Since" entry. The text has no special
internal structure. This tag means that this
change or feature has existed since the
release number of the software specified by
the since-text (such as the JDK).
@see classname Adds a hyperlinked "See Also" entry to the
class. Some examples are:
@see java.lang.String
@see String
@see String#equals
@see java.lang.Object#wait(int)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>
The character # separates the name of a class
from the name of one of its fields, methods,
or constructors. One of several overloaded
methods or constructors may be selected by
including a parenthesized list of argument
types after the method or constructor name.
White space in @see's classname is signifi-
cant. If there is more than one argument,
there must be a single blank character
between the arguments. For example:
@see java.io.File#File(java.io.File,
java.lang.String)
A doc comment may contain more than one @see
tag.
An example of a class comment:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.6, 07/23/99
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
Field Documentation Tags
A field comments can contain only the @see, @since and
@deprecated tag (as described above).
An example of a field comment:
/**
* The X-coordinate of the window.
*
* @see window#1
*/
int x = 1263732;
Constructor and Method Documentation Tags
Can contain @see tags, as well as:
@param parameter-name description
Adds a parameter to the "Parameters" section.
The description may be continued on the next
line.
@return description
Adds a "Returns" section, which contains the
description of the return value.
@exception fully-qualified-class-name description
Adds a "Throws" section, which contains the
name of the exception that may be thrown by
the method. The exception is linked to its
class documentation.
@see classname Adds a hyperlinked "See Also" entry to the
method. This tag is described above.
@since deprecated-text
See the description above.
@since since-text
See the description above.
An example of a method doc comment:
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
OPTIONS
The following options are supported:
-author Includes @author tags, which are omitted by
default.
-classpath path
NOTE: In general, do not use -classpath,
because it is normally not needed; use -
sourcepath instead to specify .java files.
Specifies the directories from which javadoc
is to load the .class files used to execute
the javadoc tool. If -sourcepath is not
specified, this also specifies the path java-
doc uses to look up the .java files to docu-
ment. It overrides the default or the
CLASSPATH environment variable, if it is set.
The path can contain multiple paths by
separating them with a colon. Set the path
the same way you do for the CLASSPATH
environment variable. For example, the fol-
lowing sets two paths: current directory (.)
and /home/opus/myclasses:
javadoc -classpath
.:/home/opus/myclasses myPackage.MyClass
The -classpath option is not necessary if you
call javadoc wrapper script directly. Nor-
mally, if you specify classpath it must pre-
cede sourcepath. However, the order of these
two options does not matter if you are using
the wrapper script.
The value of classpath defaults to the
current directory plus the classes location,
as described in the CLASSPATH environment
variable.
-d directory Specifies the destination directory where
javadoc stores the generated HTML files. (The
"d" means "destination.") The directory can
be absolute or relative to the current work-
ing directory. For example, the following
generates the documentation for the java.lang
package (using CLASSPATH to find it) and
stores the results in the directory specified
by the -d option:
example% javadoc -d
/home/opus/public_html/doc java.lang
-docencoding name
Specifies output HTML file encoding name.
-encoding name Specifies the source file encoding name, such
as EUCJIS/SJIS. If this option is not speci-
fied, the platform default converter is used.
-J flag Passes flag directly to the runtime system.
For example, if you need to ensure that the
system sets aside 32 megabytes of memory to
hold the generated documentation, then use -J
as follows:
example% javadoc -J-mx32m -J-ms32m ...
-nodeprecated Excludes paragraphs with the @deprecated tag.
Please note that the -doctype option is no
longer available. Only HTML documentation
can be produced.
-noindex Omits the default package index.
-notree Omits the default class and interface
hierarchy.
-package Shows only package, protected, and public
classes and members.
-private Shows all classes and members.
-protected Shows only protected and public classes and
members. This is the default.
-public Shows only public classes and members.
-sourcepath path
Specifies the search path for source files.
Does not affect the loading of class files.
The path you specify depends on whether you
specify packages or classes as javadoc com-
mand arguments.
When generating documentation for packages,
specify the source path as the directory in
the source tree that contains the topmost
parent package of the those you are document-
ing. The default for the source path is the
current -classpath directory. For example,
suppose you want to document a package called
java.lang whose source files are located at:
/myapp/src/share/java/lang/*.java
Because java(1) is the top-most parent pack-
age, you specify that the directory that con-
tains java as the source path.
example% javadoc -sourcepath
/myapp/src/share
When generating documentation for discrete
classes, specify the source path as the
directory in the source tree that contains
the classes you are documenting. Note that
this is different from the source path you
used when documenting packages. For example,
suppose you want to document a class named
java.lang.String whose source file is located
at:
/myapp/src/share/java/lang/String.java
Specify the directory containing the class
String.java as the source path.
example% javadoc -sourcepath
/myapp/src/share/java/lang
You can omit the -sourcepath option if you
first switch to the directory you would have
specified.
-verbose Causes the printing of additional messages
specifying the number of milliseconds taken
to parse each source file. Without the ver-
bose option, messages appear for loading the
source files, generating the documentation
(one message per source file), and sorting.
-version Includes @version tags, which are omitted by
default.
EXAMPLES
Each package name has a corresponding directory name. In the
following examples, the source files are located at
/home/ws/src/java/awt/*java. The destination directory is
/home/ws/html.
One or More Packages
To document a package, the source files (*.java) for that
package must be located in a directory having the same name
as the package. If a package name is made up of several
identifiers (separated by dots), each identifier represents
a different directory. Thus, all java.awt classes must
reside in a directory named java/awt/.
First, change to the parent directory of the topmost package
(or supply the sourcepath option with that directory). Then
run javadoc, supplying one or more fully-specified package
names. For example, if you want to document the source
files in the java.awt package located at
/home/ws/src/java/awt/*.java and its subpackage
java.awt.event:
example% cd /home/ws/src/
example% javadoc -d /home/ws/html java.awt
java.awt.event
This generates HTML-formatted documentation for the public
classes in packages java.awt and java.awt.event and puts
them in the specified destination directory (/home/ws/html).
One or More Classes
Change to the directory containing the class (or supply the
sourcepath option with that directory). Then run javadoc,
supplying one or more class names.
example% cd /home/ws/src/java/awt
example% javadoc -d /home/ws/html Button.java Canvas.java
This generates HTML-formatted documentation for the two
classes and puts them in the specified destination directory
(/home/ws/html).
ENVIRONMENT VARIABLES
CLASSPATH Used to provide the system with a path to
user-defined classes. Directories are
separated by colons, for example,
.:/home/avh/classes:/usr/local/java/classes
FILES
AllNames.html An index of members.
tree.html A hierarchy of classes.
ATTRIBUTES
See attributes(5) for a description of the following attri-
butes:
__________________________________
| ATTRIBUTE TYPE| ATTRIBUTE VALUE|
|_______________|__________________|_
| Availability | SUNWjvdev |
|_______________|_________________|
SEE ALSO
java(1), javac(1), javadoc(1), javap(1), jdb(1), jre(1),
attributes(5)
The Java Language Specification
http://java.sun.com/docs/books/jls/index.html
For information on related topics, use the search link @
http://java.sun.com/
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |