Javadoc Comments and the Java API Specification - Building Java Programs: A Back to Basics Approach - page 1122

/**
* This is a Javadoc comment.
*/

Javadoc comments may be added to class headers, methods, class constants, pub-
lic fields, and any other visible members of a class.
Many Javadoc comments also specify additional information using special syntax
called tags. A tag is an indicator for specific information such as a description of a param-
eter or return value, the author of a class, the version of a file, and so on. The information
in a tag can include boundary conditions, acceptable parameter ranges, and examples.
The syntax for tags is to write an @ sign and a tag name, followed by any additional
information. Several common Javadoc tags are described in the following table:

Tag name Description

Name(s) of the author(s) who wrote this class

@author <name>

Details about the given parameter to this method

@param <name> <description>

Details about the value that is returned by this method

@return <description>

A type of exception that this method may throw and a
description of the circumstances under which it will do so

@throws <type> <description>

Version or revision number of the file; may be a number
such as 1.2.5 or a more complex string such as a date

@version <number>

The @author and @version tags are often used on class headers. For example,
the following comment can precede the header for a Point class:

/**
* A Point object represents an ordered pair of
* (x, y) coordinates in the 2D Cartesian plane.
*
* @author Marty Stepp ([e-mail])
* @version 1.2 (January 12, 2007)
*/
public class Point {
...

}

The @param and @throws tags are often used on methods and constructors.
Non void methods may also use the @return tag. It is best to use the three preceding
tags if they supply valuable additional information that cannot be discerned from the
method's header or overall comment header.
For example, the following comment can precede the header for the distance
method of the Point class: