Java Reference
In-Depth Information
Javadoc comments are recognized when placed immediately before class, in-
terface, constructor, method, or field declarations. Documentation comments
placed in the body of a method, however useful they may be, are ignored.
Even if you do not include any comments, Javadoc will produce a listing of
classes and methods. By default, it lists public and protected methods and members
and excludes the private ones. This can be changed with command-line options.
Javadoc comments can also be marked with special markup tags, which provide
for additional formatting and cross-reference control for the generated document.
The following markup tags are used to document the interface of public methods:
@param
@return
@throws
The following markup tags are used to document packages or classes that con-
tain public methods:
@version
It is a good idea to place Javadoc comments (with at least these tags) at the be-
ginning of your classes and methods. Java programmers will expect to see them,
and several useful tools are available that will process this type of program com-
ment specification. The output of the Javadoc tool included with the SDK is espe-
cially nice looking and useful.
The advantage of in-program documentation is that, since the code and the
documentation are in the same file, the chances that the documentation will match
the code are improved. In addition, the public class interface definitions will always
be accurate because the tools automatically generate this information from the Java
source code.
One disadvantage is that you still must rely on the programmer to type in the
comments and specifications. There is no guarantee that the comments actually do
match the code. Another problem is that Java editing environments are not WYSI-
WYG graphical editors. Generating nice-looking end-user documentation with
Javadoc and HTML markups takes a lot of work, even if the end users are develop-
ers and so, presumably, have lower expectations.
Most people find it useful to include comments before method definitions and
for the class as a whole. The comments may contain special tags that Javadoc un-
derstands and can use to customize the output. These tags follow the comments.
The following shows a lightly commented source code fragment:
