Defining Classes II - Absolute Java - page 331

1. The comment must immediately precede a public class defi nition, a public method
defi nition, or other public item.
2. The comment must be a block comment (that is, the /* and */ style of comment),
and the opening /* must contain an extra *. So the comment must be marked by
/** at the beginning and */ at the end.
Unless you explicitly set an extra option to javadoc , line comments (that is, // style
comments) are not extracted, and comments preceding any private items also are not
extracted.
The comment that precedes a public method definition can include any general
information that you would like. There is also special syntax for inserting descriptions
of parameters, any value returned, and any exceptions that might be thrown. We have
not yet discussed exceptions. That is done in Chapter 9, but we include mention of
them here so this section will serve as a more complete reference on javadoc . You need
not worry about exceptions or the details about “throws” discussed here until you reach
Chapter 9 .
The special information about parameters and so forth are preceded by the @
symbol and are called @ tags . The following is an example of a method comment for
use with javadoc :

@ tag

/**
Tests for equality of two objects of type Person. To be equal,
the two objects must have the same name, same birth date, and
same death date.

@param otherPerson The person being compared to the calling
object.
@return Returns true if the calling object equals otherPerson.
*/
public boolean equals(Person otherPerson)
(The method equals is from the class Person defined in Display 5.19 . If you need
more context, look at that display.)
Note that the @ tags all come after any general comment and that each @ tag is on a
line by itself. The following are some of the @ tags allowed:

@param Parameter_Name Parameter_Description
@return Description_Of_Value_Returned
@throws Exception_Type Explanation
@deprecated
@see Package_Name.Class_Name
@author Author
@version Version_Information
The @ tags should appear in the above order—first @param , then @return , then
@throws , and so forth. If there are multiple parameters, they should each have their