Java Reference
In-Depth Information
The javadoc Documentation Tool
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
 
Search WWH ::




Custom Search