Programming and Documentation Conventions - Java in a Nutshell - page 229

@author Ben Evans
@author David Flanagan
List the authors in chronological order, with the original author first. If the
author is unknown, you can use “unascribed.” javadoc does not output author‐
ship information unless the -author command-line argument is specified.

@version text
Inserts a “Version:” entry that contains the specified text. For example:

@version 1.32 , 08 / 26 / 04
This tag should be included in every class and interface doc comment but can‐
not be used for individual methods and fields. This tag is often used in con‐
junction with the automated version-numbering capabilities of a version con‐
trol system, such as git, Perforce, or SVN. javadoc does not output version
information in its generated documentation unless the -version command-
line argument is specified.

@param parameter-name description
Adds the specified parameter and its description to the “Parameters:” section of
the current method. The doc comment for a method or constructor must con‐
tain one @param tag for each parameter the method expects. These tags should
appear in the same order as the parameters specified by the method. The tag
can be used only in doc comments for methods and constructors.
You are encouraged to use phrases and sentence fragments where possible to
keep the descriptions brief. However, if a parameter requires detailed docu‐
mentation, the description can wrap onto multiple lines and include as much
text as necessary. For readability in source-code form, consider using spaces to
align the descriptions with each other. For example:

@param o the object to insert
@param index the position to insert it at
@return description
Inserts a “Returns:” section that contains the specified description. This tag
should appear in every doc comment for a method, unless the method returns
void or is a constructor. The description can be as long as necessary, but con‐
sider using a sentence fragment to keep it short. For example:

s

@return < code > true </ code > if the insertion is successful , or
< code > false </ code > if the list already contains the object .
@exception full-classname description
Adds a “Throws:” entry that contains the specified exception name and
description. A doc comment for a method or constructor should contain an
@exception tag for every checked exception that appears in its throws clause.
For example: