Java Reference
In-Depth Information
By adding the
{@inheritDoc}
tag, we get the documentation for the interface included in
our documentation for the implementation. We can then go on to talk about the details of this
particular implementation. Note the use of the HTML tag
<p>
to indicate a paragraph break.
If we didn't include this, the inherited documentation would be in the same paragraph as the
documentation for the implementation, which is less visually appealing and could lead to con-
fusion.
Package Documentation
We've taken a look at how to use Javadoc to document interfaces and implementations. This
generates a lot of useful documentation when used correctly, and the nice thing about the doc-
umentation is that it is colocated with the code that it is describing, making it that much harder
to change one without changing the other. Of course, programmers in a hurry (or those who
hate to write anything that isn't compiled) will still avoid writing documentation, or revising
it when needed, but javadoc makes it more convenient to do the right thing and make sure that
changes in the code get described in the documentation.
If this were all that javadoc did, it would be a good thing. Indeed, this is all that most pro-
grammers use javadoc to do. But there is a missing piece of the documentation if all that
is described are the interfaces and classes. What hasn't been shown yet is how all of those
pieces are meant to fit together to form a system. This is the architecture of the system, and it
provides a framework for the reader of the documentation to put the pieces into place and see
the system as a system. Although the individual class and interface entries may tell the reader
how the pieces function individually, it is this broader documentation that tells the reader the
structure that unifies those pieces.
Javadoc supplies a mechanism for this kind of architectural documentation, which is (unfor-
tunately) often either unknown, ignored, or abused. This mechanism is the package comment
file, which I mentioned earlier in this chapter. In any package, you can include a file that can
be used to specify the architectural documentation for the package. Prior to JDK 5.0, this file
was named
package.html
, and was a standard HTML file that could contain documentation
about the package. Since JDK 5.0, this file can be a java source file containing the package de-
claration, package annotations, and the documentation (including all of the standard javadoc
tags).
Such comment files need not be huge. For example, a reasonable comment for our statistics
package might look something like:
