Java Reference
In-Depth Information
/**
* Return a <code>String</code> that is the name of the
* team for this player.
*/
Team getTeam();
/**
* Return the <code>Position</code> played by this player
* @return the <code>Position</code> of this player,
* which will be used to determine the roles that the
* player has.
*/
Position getPosition();
/**
* Set the <code>Position</code> of the player
* @param pos the <code>Position</code> played
* by this player.
*/
void setPosition(Position pos);
}
The good news here is that there is some documentation that Javadoc can format. The inter-
face has a comment on the purpose of the interface, and each method has a line or two stating
what that method does. There is even the HTML markup to visually distinguish the parts of
the comment that should be understood as references to code from those that are not. For one
of the methods with a return value, an
@return
tag is specified, and for the method with an
argument, the
@param
tag is specified.
The document produced by the Javadoc tool from this small amount of source is fairly im-
pressive. It will have a summary of the interface, taken from the first line of the doc comment
prior to the declaration of the interface. It will list all of the methods, with their signature and
a one-line summary of what the method does, again taken from the first line of the doc com-
ment. Finally, each of the methods will be separately documented, using all of the informa-
tion in the doc comment for that method, including links to the parameters and return value
classes. Note that the first line of a documentation comment for a class, interface, or method
is automatically used as the summary documentation, so that line should carefully encapsulate
the important aspects of the documentation. In javadoc, as in so much else in life, first impres-
sions are important.
