Java Reference
In-Depth Information
documented features and not on implementation details. Good javadoc will specify the se-
mantics of an interface in the documentation for that interface, and will use the documentation
for the classes that implement the interface to discuss only the features of that implementa-
tion. Indeed, a good rule of system development is to write the javadoc for the interfaces first,
and then use that documentation as a form of specification for any classes that implement the
An Example
Rather than trying to give a full tutorial on the capabilities of Javadoc (which can be found at ) , let's look at an example.
One of the places where it is important to fully document our code is when we declare an in-
terface, since it is the documentation that will tell those implementing or using that interface
what the intended semantics are. So let's take a look at our Player interface:
package org.oreilly.javaGoodParts.examples.statistics;
import java.util.UUID;
*Basic interface for a player object.
public interface Player {
enum Position {
Pitcher, Catcher, FirstBase, SecondBase,
ThirdBase, ShortStop, LeftField, CenterField,
RightField, DH, Utility
* Return the identifier for the player. This is just
* a <code>UUID</code>, generated when the player object is
* first created, used to distinguish between players
* that might have the same name.
UUID getId();
* Return the name of the player, as a <code>String</code>
String getName();
Search WWH ::

Custom Search