Java Reference
In-Depth Information
In addition, each complete project should have an overall project comment, often contained in
a “ReadMe” file. In BlueJ, this project comment is accessible through the text note displayed in
the top left corner of the class diagram.
Exercise 5.46 Use BlueJ's Project Documentation function to generate documentation for
your TechSupport project. Examine it. Is it accurate? Is it complete? Which parts are useful?
Which are not? Do you find any errors in the documentation?
Some elements of the documentation, such as names and parameters of methods, can always be
extracted from the source code. Other parts, such as comments describing the class, methods, and
parameters, need more attention, as they can easily be forgotten, be incomplete, or be incorrect.
In Java, javadoc comments are written with a special comment symbol at the beginning:
/**
This is a javadoc comment.
*/
The comment start symbol must have two asterisks to be recognized as a javadoc comment.
Such a comment immediately preceding the class declaration is read as a class comment. If the
comment is directly above a method signature, it is considered a method comment.
The exact details of how documentation is produced and formatted are different in different pro-
gramming languages and environments. The content, however, should be more or less the same.
In Java, using javadoc , several special key symbols are available for formatting the documen-
tation. These key symbols start with the @ symbol and include
@version
@author
@param
@return
Exercise 5.47 Find examples of javadoc key symbols in the source code of the
TechSupport project. How do they influence the formatting of the documentation?
Exercise 5.48 Find out about and describe other javadoc key symbols. One place
where you can look is the online documentation of Oracle's Java distribution. It contains a
document called javadoc - The Java API Documentation Generator (for example, at http://
download.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.
html ). In this document, the key symbols are called javadoc tags .
Exercise 5.49 Properly document all classes in your version of the TechSupport project.
5.11
Public versus private
It is time to discuss in more detail one aspect of classes that we have encountered several times
already without saying much about it: access modifiers.
 
Search WWH ::




Custom Search