Spurious Javadoc @param tags¶
ID: java/unknown-javadoc-parameterKind: problemSecurity severity: Severity: recommendationPrecision: very-highTags: - quality - maintainability - readabilityQuery suites: - java-security-and-quality.qls
Click to see the query in the CodeQL repository
Javadoc comments for public methods, constructors and generic classes should use the@param tag to describe the available parameters and type parameters. If the comment includes any empty, incorrect or outdated parameter names then this will make the documentation more difficult to read.
Recommendation¶
The Javadoc comment for a method, constructor or generic class should always use non-empty@param values that match actual parameter or type parameter names.
Example¶
The following example shows good and bad Javadoc comments that use the@param tag.
/** * BAD: The following param tag is empty. * * @param */publicvoidemptyParamTag(intp){...}/** * BAD: The following param tag has a misspelled value. * * @param prameter The parameter's value. */publicvoidtypo(intparameter){...}/** * BAD: The following param tag appears to be outdated * since the method does not take any parameters. * * @param sign The number's sign. */publicvoidoutdated(){...}/** * BAD: The following param tag uses html within the tag value. * * @param <code>ordinate</code> The value of the y coordinate. */publicvoidhtml(intordinate){...}/** * BAD: Invalid syntax for type parameter. * * @param T The type of the parameter. * @param parameter The parameter value. */public<T>voidparameterized(Tparameter){...}/** * BAD: The following param tag refers to a non-existent type parameter. * * @param <X> The type of the elements. */classGeneric<T>{...}/** * GOOD: A proper Javadoc comment. * * This method calculates the absolute value of a given number. * * @param <T> The number's type. * @param x The number to calculate the absolute value of. * @return The absolute value of <code>x</code>. */public<TextendsNumber>Tabs(Tx){...}
References¶
Help - Eclipse Platform:Java Compiler Javadoc Preferences.
Java SE Documentation:How to Write Doc Comments for the Javadoc Tool,Documentation Comment Specification for the Standard Doclet