Java Reference
In-Depth Information
have in our documentation. Since any valid HTML can also be used, we can include links to
outside documents, websites, or even videos. This ability should be used judiciously (after all,
this is documentation that is meant to be read online by developers; they are trying to get a
job done, not reading for recreation). But here it might make sense to include references to the
definitions of some of the more obscure batting or fielding statistics in the documentation for
our
Batter
or
Fielder
interfaces. For example, we might want to change our documentation
comment for the
getOBP()
method to something like:
/**
* Returns the on-base percentage for this hitter,
* <a href="http://en.wikipedia.org/wiki/On_base_percentage">defined</a>
* as (hits + walks)/at-bats
* @return the on-base percentage
* @throws NotEnoughAtBatsException if the number of at-bats, walks,
* and sacrifices is insufficient to establish a meaningful on-base
* percentage
*/
which includes a link to the Wikipedia article that gives the definition of on-base percentage.
This sort of thing can be taken to extremes pretty easily, but it is a capability that, if used oc-
casionally, can make your documentation much clearer than it would be without the outside
references.
Implementation Documentation
Thus far, we have been looking mostly at the javadoc for interfaces. The documentation for
an interface can be thought of as a specification for any class that implements that interface.
But what about the classes themselves? Do they need the same kind of javadoc?
If you don't do anything (that is, if you don't write any documentation comments for an imple-
mentation class), a class that implements an interface will inherit the documentation from the
interface that it implements. The documentation will show this, with the Javadoc tool insert-
ing the phrase “Description copied from interface:” and the interface name at the beginning of
the description. At worst, you will get the specification of the method in the implementation
class. But we can do a lot better than that.
The first thing that we can do better is to use the
{@inheritDoc}
tag to get the documentation
contents of the closest ancestor in the inheritance hierarchy. In our simple example, this is
the same as letting the interface documentation be copied in, with the only visible difference
