Objects and classes - Data Structures and Problem Solving Using Java - page 74

The Java implementation file can also add javadoc comments that begin
with the comment starter token /** . Those comments are automatically added
in a uniform and consistent manner to the documentation produced by javadoc .

There also are several special tags that can be included in the javadoc com-
ments. Some of these are @author , @param , @return , and @throws . Figure 3.4 illustrates
the use of the javadoc commenting features for the IntCell class. At line 3, the
@author tag is used. This tag must precede the class definition. Line 10 illustrates the
use of the @return tag, line 19 the @param tag. These tags must appear prior to a
method declaration. The first token that follows the @param tag is the parameter
name. The @throws tag is not shown, but it has the same syntax as @param .
Some of the output that results from running javadoc is shown in
Figure 3.5. Run javadoc by supplying the name (including the .java exten-
sion) of the source file.
The output of javadoc is purely commentary except for the method headers.
The compiler does not check that these comments are implemented. Nonetheless,
the importance of proper documentation of classes can never be overstated. javadoc
makes the task of generating well-formatted documentation easier.

javadoc tags
include @author ,
@param , @return ,
and @throws . They
are used in
javadoc comments.

figure 3.4
The IntCell
declaration with
javadoc comments

1 /**
2 * A class for simulating an integer memory cell
3 * @author Mark A. Weiss
4 */
5
6 public class IntCell
7 {
8 /**
9 * Get the stored value.
10 * @return the stored value.
11 */
12 public int read( )
13 {
14 return storedValue;
15 }
16
17 /**
18 * Store a value.
19 * @param x the number to store.
20 */
21 public void write( int x )
22 {
23 storedValue = x;
24 }
25
26 private int storedValue;
27 }