Java Reference
In-Depth Information
The Java documentation creator,
javadoc
, takes a
.java
source code file or package
name as input and generates detailed documentation in HTML format.
For
javadoc
to create full documentation for a program, a special type of comment state-
ment must be used in the program's source code. Tutorial programs in this topic use
//
,
/*
, and
*/
in source code to create
comments
—information for people who are trying to
make sense of the program.
Java also has a more structured type of comment that can be read by the
javadoc
tool.
This comment is used to describe program elements such as classes, variables, objects,
and methods. It takes the following format:
B
/**
A descriptive sentence or paragraph.
* @
tag1 Description of this tag.
* @
tag2 Description of this tag.
*/
A Java documentation comment should be placed immediately above the program ele-
ment it is documenting and should succinctly explain what the program element is. For
example, if the comment precedes a
class
statement, it will describe the purpose of the
class.
In addition to the descriptive text, different items can be used to document the program
element further. These items, called
tags
, are preceded by an
@
sign and are followed by
a space and a descriptive sentence or paragraph.
Listing B.3 contains a thoroughly documented version of the
AppInfo
applet called
AppInfo2
. The following tags are used in this program:
@author
—The program's author. This tag can be used only when documenting a
class, and it will be ignored unless the
-author
option is used when
javadoc
is
run.
n
@version
text
—The program's version number. This also is restricted to class
documentation, and it requires the
-version
option when you're running
javadoc
,
or the tag will be ignored.
n
@return
text
—The variable or object returned by the method being documented.
n
@serial
text
—A description of the data type and possible values for a variable or
object that can be
serialized
, saved to disk along with the values of its variables
and retrieved later.
n