Java Reference
In-Depth Information
Code I.1
The main description
of a class comment
/**
* This class is the main class of the "World of Zuul".
* application
* "World of Zuul" is a very simple, text-based adventure game.
* Users can walk around some scenery. That's all. It should
* really be extended to make it more interesting!
* To play this game, create an instance of this class and call
* the "play" method.
*/
The main description for a method should be kept fairly general, without going into a lot of
detail about how the method is implemented. Indeed, the main description for a method will
often only need to be a single sentence, such as
/**
* Create a new passenger with distinct pickup and destination
* locations.
*/
Particular thought should be given to the first sentence of the main description for a class, inter-
face, or method, as it is used in a separate summary at the top of the generated documentation.
Javadoc also supports the use of HTML markup within these comments.
I.1.2 The tag section
Following the main description comes the tag section . Javadoc recognizes around 20 tags, of
which we discuss only the most important here (Table I.1). Tags can be used in two forms:
block tags and in-line tags . We shall only discuss block tags, as these are the most commonly
used. Further details about in-line tags and the remaining available tags can be found in the
javadoc section of the Tools and Utilities documentation that is part of the JDK.
Table I.1
Common javadoc
tags
Tag
Associated text
author name(s)
@author
parameter name and description
@param
@return
description of the return value
@see
cross-reference
@throws
exception type thrown and the circumstances
@version
version description
The @author and @version tags are regularly found in class and interface comments and can-
not be used in constructor, method, or field comments. Both are followed by free-text, and there
is no required format for either. Examples are
@author Hacker T. Largebrain
@version 2012.12.03
Search WWH ::




Custom Search