Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
@param (reference page)
The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.
Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class. The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it.
Example:
* @param ch the character to be tested
* @param observer the image observer to be notified
Do not bracket the name of the parameter after the @param tag with <code>...</code> since Javadoc 1.2 and later automatically do this. (Beginning with 1.4, the name cannot contain any HTML, as Javadoc compares the @param name to the name that appears in the signature and emits a warning if there is any difference.)
When writing the comments themselves, in general, start with a phrase and follow it with sentences if they are needed.
When writing a phrase, do not capitalize and do not end with a period:
@param x the x-coordinate, measured in pixels
When writing a phrase followed by a sentence, do not capitalize the phrase, but end it with a period to distinguish it from the start of the next sentence:
@param x the x-coordinate. Measured in pixels.
If you prefer starting with a sentence, capitalize it and end it with a period:
@param x Specifies the x-coordinate, measured in pixels.
When writing multiple sentences, follow normal sentence rules:
@param x Specifies the x-coordinate. Measured in pixels.
Also see order of multiple @param tags.
Guidelines
This chapter contains mainly two guidelines:
-
The @param tag is followed by the name (not data type) of the parameter
-
...followed by a description of the parameter
Rule number 1 is enforced by JavadocMethod.
Rule number 2 is enforced by NonEmptyAtclauseDescription
Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
@param (reference page)
The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.
Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class. The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it.
Example:
Do not bracket the name of the parameter after the @param tag with
<code>...</code>since Javadoc 1.2 and later automatically do this. (Beginning with 1.4, the name cannot contain any HTML, as Javadoc compares the @param name to the name that appears in the signature and emits a warning if there is any difference.)When writing the comments themselves, in general, start with a phrase and follow it with sentences if they are needed.
When writing a phrase, do not capitalize and do not end with a period:
When writing a phrase followed by a sentence, do not capitalize the phrase, but end it with a period to distinguish it from the start of the next sentence:
If you prefer starting with a sentence, capitalize it and end it with a period:
When writing multiple sentences, follow normal sentence rules:
Also see order of multiple @param tags.
Guidelines
This chapter contains mainly two guidelines:
Rule number 1 is enforced by JavadocMethod.
Rule number 2 is enforced by NonEmptyAtclauseDescription