Javadoc - Objects First with Java: A Practical Introduction Using BlueJ - page 528

APPENDIX

I

Javadoc

Writing good documentation for class and interface definitions is an important complement to
writing good-quality source code. Documentation allows you to communicate your intentions
to human readers in the form of a natural-language, high-level overview, rather than forcing
them to read relatively low-level source code. Of particular value is documentation for the
public elements of a class or interface, so that programmers can make use of it without having
to know the details of its implementation.

In all of the project examples in this topic, we have used a particular commenting style that is
recognized by the javadoc documentation tool, which is distributed as part of the JDK. This
tool automates the generation of class documentation in the form of HTML pages in a consist-
ent style. The Java API has been documented using this same tool, and its value is appreciated
when using library classes.
In this appendix, we give a brief summary of the main elements of the documentation com-
ments that you should get into the habit of using in your own source code.

I.1 Documentation comments

The elements of a class to be documented are the class definition as a whole, its fields, construc-
tors, and methods. Most important from the viewpoint of a user of your class is to have docu-
mentation for the class and its public constructors and methods. We have tended not to provide
javadoc-style commenting for fields, because we regard these as private implementation-level
details and not something to be relied upon by users.

Documentation comments are always opened with the character triplet “/**” and closed by the
character pair “*/”. Between these symbols, a comment will have a main description followed
by a tag section , although both are optional.

I.1.1 The main description
The main description for a class should be a general description of the purpose of the
class. Code I.1 shows part of a typical main description, taken from the Game class of the
world-of-zuul project. Note how the description includes details of how to use this class to
start the game.