More-sophisticated behavior - Objects First with Java: A Practical Introduction Using BlueJ - page 182

class from our last example, someone else might implement the InputReader . Thus, you
might write one class while making calls to methods of other classes.

The same argument discussed for library classes holds true for classes that you write: if we
can use the classes without having to read and understand the complete implementation, our
task becomes a lot easier. As with library classes, we want to see just the public interface of the
class, instead of the implementation. It is therefore important to write good class documentation
for our own classes as well.

Java systems include a tool called javadoc that can be used to generate such an interface de-
scription from source files. The standard library documentation that we have used, for example,
was created from the classes' source files by javadoc .

5.10.1 Using javadoc in BlueJ

The BlueJ environment uses javadoc to let you create documentation for your class in two
ways:

■ You can view the documentation for a single class by switching the pop-up selector at the
top right of the editor window from Source Code to Documentation (or by using Toggle
Documentation View from the editor's Tools menu).
■ You can use the Project Documentation function from the main window's Tools menu to
generate documentation for all classes in the project.

The BlueJ tutorial provides more detail if you are interested. You can find the BlueJ tutorial in
BlueJ's Help menu.

5.10.2 Elements of class documentation

The documentation of a class should at least include:

■ the class name
■ a comment describing the overall purpose and characteristics of the class
■ a version number

■ the author's name (or authors' names)
■ documentation for each constructor and each method
The documentation for each constructor and method should include:

■ the name of the method

■ the return type
■ the parameter names and types

■ a description of the purpose and function of the method

■ a description of each parameter
■ a description of the value returned