InappropriateJavadocBlockTagsOnType
Since Checkstyle 14.1.0
Description
Checks that Javadoc block tags for type definitions (class, interface, enum, record, annotation) do not contain tags that are semantically invalid for types. Specifically,
@return and @throws/@exception tags are meaningless on type declarations since types neither return values nor throw exceptions.
Type declarations (classes, interfaces, enums, records, annotations) do not have return types or throw declarations. Therefore, @return and @throws/@exception Javadoc block tags used in their Javadoc comments are considered inappropriate and should be removed or replaced with proper documentation.
Properties
| name | description | type | default value | since |
|---|---|---|---|---|
| violateExecutionOnNonTightHtml | Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. | boolean | false |
14.1.0 |
Examples
To configure the check to report inappropriate type Javadoc block tags:
<module name="Checker">
<module name="TreeWalker">
<module name="InappropriateJavadocBlockTagsOnType"/>
</module>
</module>
Example:
/**
* @return a value
*/
class MyClass1 {
// violation above 'Invalid '@return' tag for 'MyClass1'.'
}
/**
* @param <T> a value
*/
class MyClass2<T> {
}
/**
* @return a value
*/
enum MyEnum1 {
// violation above 'Invalid '@return' tag for 'MyEnum1'.'
}
/**
* Valid Javadoc
*/
enum MyEnum2 {
}
/**
* @return a value
* @param <T> a value
*/
interface MyInterface1<T> {
// violation above 'Invalid '@return' tag for 'MyInterface1'.'
}
/**
* Valid Javadoc
*/
interface MyInterface2 {
}
/**
* @return a value
*/
record MyRecord1(String name, int age) {
// violation above 'Invalid '@return' tag for 'MyRecord1'.'
}
/**
* Valid Javadoc
*/
record MyRecord2(String name, int age) {
}
Example of Usage
Violation Messages
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
Fully Qualified Name
com.puppycrawl.tools.checkstyle.checks.javadoc.InappropriateJavadocBlockTagsOnTypeCheck
Use this fully qualified class name in configuration when an exact class reference is required.