Java Reference
In-Depth Information
being that the comment “Description copied from interface:” is not inserted. But if we start
inheriting the implementation as well as just the interface, the difference is important. Inher-
iting the documentation will now cause any implementation comments on the superclass to
be brought into the documentation on the new class, rather than just the documentation of the
interface. Using the {@inheritDoc} tag is a good habit to get into.
For example, consider the method getId in the Player interface. The documentation comment
for the Player interface tells us that this method should return the ID for the player. We know
that the ID should be unique over the set of all players, but it would be nice to know how the
implementation ensures this. One alternative would be to have the javadoc for the method in
the PlayerImpl say something like:
/**
* This implementation will generate a player
* id by using the standard {@link UUID#randomUUID}
* generator for UUIDs, which is a cryptographically
* strong UUID. This should guarantee enough
* uniqueness for this application.
* @return the UUID that is the player id
*/
This is helpful, but in doing this, we lose the documentation for the method that we wrote for
the interface. We could always put a pointer to the interface somewhere in the implementation
documentation, but then we will have the user of the documentation jumping from entry to
entry in the document, which can be annoying (and error-prone). A better solution is to inherit
the documentation from the interface, and then augment that documentation with details about
this implementation of the interface. We can use the {@inheritDoc} tag for this, and conse-
quently we will get a better form of documentation, which looks like:
/**
* {@inheritDoc }
* <p>
* This implementation will generate a player
* id by using the standard {@link UUID#randomUUID}
* generator for UUIDs, which is a cryptographically
* strong UUID. This should guarantee enough
* uniqueness for this application.
* @return the UUID that is the player id
*/
Search WWH ::




Custom Search