Javadoc - Java: The Good Parts - page 87

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
interface.
An Example
Rather than trying to give a full tutorial on the capabilities of Javadoc (which can be found at
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html ) , 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();