Defining Classes II - Java - page 319

1. The comment must immediately precede a public class definition, a public method
definition, 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 you wish it to. 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 . Below 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