Documentation comments are used to create stand-alone documentation for classes. Documentation comments are processed into Web pages by the javadoc program that is part of Sun's Java Development Kit (JDK). The javadoc program and the way that it processes .java files into Web pages is fully described in the documentation for javadoc provided by Sun. The remainder of this section describes the special formatting information that can be embedded in documentation comments.
Documentation comments are comments that begin with /**. If a documentation comment immediately precedes the declaration of a class, interface, method, or field variable, it is assumed to describe that class, interface, method, or field variable.
HTML tags can be included in a documentation comment; they are passed directly to the generated Web page. In addition to passing HTML tags, javadoc recognizes special tags that start with an "at" sign (@). These tags must appear as the first word on a line in order to be recognized. Here is an example of a documentation comment that includes these special javadoc tags:
/** * RomanNumeral is a class similar to Integer, except that * it uses roman numerals for its string based * representation. It only represents positive numbers. * * @see Integer * @see Number * @see Float * @see Double * @version 1.1, 9/27/96 * @author Mark Grand */
Here are the special documentation comment tags recognized by javadoc :
The documentation comment that immediately precedes a declaration is associated with the declaration. If two comments precede a declaration, only the one immediately preceding the declaration is processed by javadoc. The first comment is not considered to be associated with a declaration, so it is ignored. If there is anything but white space between a documentation comment and a declaration, the documentation comment is not considered to be associated with the declaration.