Java Reference
In-Depth Information
you can't include documentation comments inside the body of method, but if you do, those
comments will be interpreted as standard block comments and ignored by the Javadoc tool.
There are also files that contain nothing but documentation comments. Every package can
contain a special file that can be used to document the overall structure of that package.
Known as package comment files, these should be placed at the root of the package. Prior to
Java 5.0, these files were named
package.html
; since Java 5.0, you can also use the filename
package-info.java
.
The Javadoc tool is the program that turns your comments into HTML files. Since the tool
creates HTML, you can embed HTML into your comments and have those appear (correctly)
in the pages generated by the Javadoc tool. This means that all of the formatting mechanisms
that are contained in HTML can be used to write your documentation inside your source code.
This also means that, if you want to, you can include videos or entire websites in your doc-
umentation. Good taste, and the knowledge that your coworkers might be able to find you,
should dictate restraint in using such features.
There are also special
tags
that can be used within a documentation comment that the tool will
use to create links within the generated documentation. For example, if you need to refer to
another class in your documentation, you can enter
{@link
packagename#classname}
and
a link to that class's documentation will be inserted in the generated document. You can do
the same thing with an interface, using
{@link
packagename#interfacename}
. Other tags
can be used for everything from the name of the author of the code to the parameters, return
values, and exceptions for a method. One of the more useful tags is
{@inheritDoc}
, which
allows you to inherit the documentation comments from the nearest relative in the type hier-
archy. We will see how this works later, but it saves immense amounts of copying and much
of the pain of keeping documentation consistent over a system.
The end result of properly written documentation comments run through the Javadoc tool is a
set of web pages that act as online documentation for your system. The documentation uses all
of the hypertext capabilities inherent in the Web, allowing readers to traverse from one class
or interface to another. Even better, most IDEs (which, once again, mostly means both Eclipse
and Netbeans) will now display the documentation comments for code that is being used by
a programmer as part of their online documentation. So by writing good documentation com-
ments, we not only get better browser-enabled documentation but online, IDE-accessible doc-
umentation as well. All colocated with the source code. Such a deal.
Properly written javadoc encourages and supports good object-oriented hygiene in a number
of ways. Good javadoc supplies API documentation that can be shipped (and viewed) separ-
ately from the implementation of the API, encouraging users of the code to rely only on the
