Defining Classes II - Absolute Java - page 330

Introduction to javadoc ★
The principles of encapsulation using information hiding say that you should separate
the interface of a class (the instructions on how to use the class) from the implementation
(the detailed code that tells the computer how the class does its work). In some other
programming languages, such as C++, you normally define a class in two files. One file
contains something like the interface or API that tells a programmer all that he or she
needs to know to use the class. The other file contains the implementation details that
are needed for the class code to run. This system is an obvious way to separate interface
from implementation, but it is not what Java does.
Java does not divide a class definition into two files. Instead, Java has the interface
and implementation of a class mixed together into a single file. If this were the end of
the story, Java would not do a good job of encapsulation using information hiding.
However, Java has a very good way of separating the interface from the implementation
of a class. Java comes with a program named javadoc that automatically extracts the
interface from a class definition. If your class definition is correctly commented, a
programmer using your class need only look at this API (documentation) produced
by javadoc . The documentation produced by javadoc is identical in format to the
documentation for the standard Java library classes.
The result of running javadoc on a class is to produce an HTML file with the
API (interface) documentation for the class. HTML is the basic language used to
produce documents to view with a Web browser, so the documentation produced
by javadoc is viewed on a Web browser. A brief introduction to HTML is given in
Chapter 20. However, you need not know any HTML to run javadoc or to read the
documentation it produces.
javadoc can be used to obtain documentation for a single class. However, it is
primarily intended to obtain documentation for an entire package.
We will first discuss how you should comment your classes so that you can get the
most value out of javadoc . We will then describe how you run the javadoc program.

javadoc

Commenting Classes for javadoc ★
To get a more useful javadoc document, you must write your comments in a
particular way. All the classes in this topic have been commented for use with javadoc .
However, to save space, the comments in this topic are briefer than what would be
ideal for javadoc .
The javadoc program extracts the heading for your class (or classes) as well as
the headings for all public methods, public instance variables, public static variables,
and certain comments. No method bodies and no private items are extracted when
javadoc is run in the normal default mode.
For javadoc (in default mode) to extract a comment, the comment must satisfy
two conditions: