Defining Classes II - Java - page 318

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 implementa-
tion (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 sep-
arate 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 implementa-
tion 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 docu-
mentation 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 18.
However, you need not know any HTML to run javadoc or to read the documenta-
tion it produces.
javadoc can be used to obtain documentation for a single class. However, it is pri-
marily 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 particu-
lar 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: