Documentation Comments - Beginning Java 8 Fundamentals - page 734

* @param n1 The multiplicand
* @param n2 The multiplier
* @return Returns the result of multiplication of <code>n1</code> and <code>n2</code>
*/
public static int multiply(int n1, int n2) {
return n1 * n2;
}
The following is an example of using the @param tags to document the type parameters of a class:
/**
* Wraps an object of any type.
*
* @param <T> Type of the object wrapped in the Wrapper
*/
public class Wrapper<T> {
// Code for the Wrapper class goes here
}
@return <description>
It is valid only for methods. It adds a Returns section with the specified description . The specified description
should contain the return type and the description of value that is returned from the method. Please refer to the
example of the @param tag to see how to use @return tag in a documentation comment.
@see <reference>
It adds a See Also section with a link or text that points to the specified reference . A documentation comment can
have multiple @see tags. All @see tags will be displayed under one See Also section for a documentation comment.
You can specify the reference in one of the three following forms:
@see "text"
@see <a href="URL">label</a>
@see package.Classname#member label
In the first form, the reference is specified as a text that is enclosed in double quotes. The javadoc tool adds the
specified text in the See Also section, without any link.
In the second form, the reference is specified using an HTML anchor tag (<a> tag). The javadoc tool generates a
hyperlink that points to the specified URL . If specified, the specified label is displayed as the link text.
In the third form, the reference is specified to a class, an interface, a field, a constructor, or a method. Note that if
you are referencing a field, a constructor, or a method, its name is preceded by a hash sign ( # ), not a dot. The javadoc
tool generates a link to the reference that has the specified label as the visible text. The label is optional. If label is
omitted, the tool uses a suitable text for the link that is derived from the first argument to the @see tag. The reference
to the program element could use the fully qualified name or a partial name. The tool uses the same rules as the Java
compiler to resolve the partial name of a program element.