虚假 Javadoc @param 标签¶
ID: java/unknown-javadoc-parameter
Kind: problem
Security severity:
Severity: recommendation
Precision: very-high
Tags:
- maintainability
Query suites:
- java-security-and-quality.qls
公共方法、构造函数和泛型类的 Javadoc 注释应使用 @param 标签来描述可用的参数和类型参数。如果注释包含任何空、不正确或过时的参数名，这将使文档更难阅读。
建议¶
方法、构造函数或泛型类的 Javadoc 注释应始终使用与实际参数或类型参数名匹配的非空 @param 值。
示例¶
以下示例显示了使用 @param 标签的良好和不良 Javadoc 注释。
/**
* BAD: The following param tag is empty.
*
* @param
*/
public void emptyParamTag(int p){ ... }
/**
* BAD: The following param tag has a misspelled value.
*
* @param prameter The parameter's value.
*/
public void typo(int parameter){ ... }
/**
* BAD: The following param tag appears to be outdated
* since the method does not take any parameters.
*
* @param sign The number's sign.
*/
public void outdated(){ ... }
/**
* BAD: The following param tag uses html within the tag value.
*
* @param <code>ordinate</code> The value of the y coordinate.
*/
public void html(int ordinate){ ... }
/**
* BAD: Invalid syntax for type parameter.
*
* @param T The type of the parameter.
* @param parameter The parameter value.
*/
public <T> void parameterized(T parameter){ ... }
/**
* BAD: The following param tag refers to a non-existent type parameter.
*
* @param <X> The type of the elements.
*/
class Generic<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 <T extends Number> T abs(T x){ ... }
参考资料¶
帮助 - Eclipse 平台：Java 编译器 Javadoc 首选项.
Java SE 文档：如何为 Javadoc 工具编写文档注释，标准 Doclet 的文档注释规范