Javadoc - Java: The Good Parts - page 89

What we have in the example is a lot better than much of the documentation that I have seen,
which often is either the name of the function and the names of the parameters and return val-
ues or the even more common “tbd.” But there is a lot more that can, and should, be done.
Let's start at the top. Saying that this is the basic interface for the Player object is true, but
not particularly informative. Why do we have a Player interface, rather than relying on the
previous interfaces that we defined, such as Batter and Fielder ? How will the player object
be used? The documentation that we have supplied is fine for the summary of the class, but it
doesn't do much to fill in details beyond the summary.
A much better summary of the interface would look something like:
/**
* Basic interface for a player object. An object implementing
* this interface can be made part of a {@link Team}. Classes
* implementing this interface will also allow access to statistics
* gathered for the player in the form of objects of type
* {@link Batter}, {@link Fielder}, or {@link Catcher}. Which
* of these roles will be had by a Player will in part be determined
* by the {@link Position} of the Player.
*/
This lets us relate the Player object to the objects that will contain them (the Team objects).
It also says how the interface relates to some of the other interfaces that we have defined in
our statistics package, pointing out that Player objects can be used to get instances of objects
that implement the Batter , Fielder , or Catcher interfaces, depending on the value of the
Position contained in the Player object. This is only a few more lines and didn't take that
long to write, but now we can relate our Player interface to the other interfaces that we have
defined, and the reader can get an understanding of how the Player interface will be used.
There are a lot of other things that could go into documenting the interface. We could talk
about the invariants that need to be met by any implementation of the interface. We could spe-
cify the locking protocols followed, assumed, or required. We could specify the expected life
cycle of objects that implement the interface. And we could give a description of how clients
might use objects that support the interface.
Now let's take a look at the documentation comments for the various methods. Although it is
nice that we have indicated the programming language constructs by putting them into a code
font (using HTML), it would be better if we used the javadoc {@link } construct to not only
show that these are references to Java types but to actually link to those types. While looking