Since Checkstyle 3.0
Checks the Javadoc comments for type definitions.
By default, does not check for author or version tags. The
scope to verify is specified using the Scope
class and defaults to Scope.PRIVATE. To verify
another scope, set property scope to one of the
Scope constants. To define the format for an
author tag or a version tag, set property authorFormat or
versionFormat respectively to a
pattern.
Does not perform checks for author and version tags for inner classes, as they should be redundant because of outer class.
Does not perform checks for type definitions that do not have any Javadoc comments.
Error messages about type parameters and record components for which no
param tags are present can be suppressed by defining property
allowMissingParamTags.
| name | description | type | default value | since |
|---|---|---|---|---|
| allowMissingParamTags | Control whether to ignore violations when a class has type parameters but does not have matching param tags in the Javadoc. | boolean | false |
4.0 |
| allowUnknownTags | Control whether to ignore violations when a Javadoc tag is not recognised. | boolean | false |
5.1 |
| allowedAnnotations | Specify annotations that allow skipping validation at all. Only short names are allowed, e.g. Generated. |
String[] | Generated |
8.15 |
| authorFormat | Specify the pattern for @author tag. |
Pattern | null |
3.0 |
| excludeScope | Specify the visibility scope where Javadoc comments are not checked. | Scope | null |
3.4 |
| scope | Specify the visibility scope where Javadoc comments are checked. | Scope | private |
3.0 |
| versionFormat | Specify the pattern for @version tag. |
Pattern | null |
3.0 |
| tokens | tokens to check | subset of tokens INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , RECORD_DEF . | INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , RECORD_DEF . | 3.0 |
To configure the default check:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType"/>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK
}
/**
* @author
* @version abc
* @unknownTag value // violation
*/
public class ClassC {} // OK
/** */
public class ClassD<T> {} // violation, as param tag for <T> is missing
/** */
private class ClassE<T> {} // violation, as param tag for <T> is missing
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check for public scope:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="scope" value="public"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK
}
/**
* @author
* @version abc
* @unknownTag value // violation
*/
public class ClassC {} // OK
/** */
public class ClassD<T> {} // violation, as param tag for <T> is missing
/** */
private class ClassE<T> {} // OK
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check for an @author tag:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="authorFormat" value="\S"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK, as author tag check is ignored for inner class
}
/**
* @author
* @version abc
* @unknownTag value // violation
*/
public class ClassC {} // violation, as author format with only whitespace or new line is invalid
/** */
public class ClassD {} // violation, as author tag is missing
/** */
private class ClassE {} // violation, as author tag is missing
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check for a CVS revision version tag:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="versionFormat" value="\$Revision.*\$"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK, as version tag check is ignored for inner class
}
/**
* @author
* @version abc
* @unknownTag value // violation
*/
public class ClassC {} // violation, as version format is invalid
/** */
public class ClassD {} // violation, as version tag is missing
/** */
private class ClassE {} // violation, as version tag is missing
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check for private classes only:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="scope" value="private"/>
<property name="excludeScope" value="package"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK
}
/**
* @author
* @version abc
* @unknownTag value // OK
*/
public class ClassC {} // OK
/** */
public class ClassD<T> {} // OK
/** */
private class ClassE<T> {} // violation, as param tag for <T> is missing
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check that allows missing @param tags:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="allowMissingParamTags" value="true"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK
}
/**
* @author
* @version abc
* @unknownTag value // violation
*/
public class ClassC {} // OK
/** */
public class ClassD<T> {} // OK, as missing param tag is allowed
/** */
private class ClassE<T> {} // OK, as missing param tag is allowed
/** */
@Generated
public class ClassF<T> {} // OK
To configure the check that allows unknown tags:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="allowUnknownTags" value="true"/>
</module>
</module>
</module>
Example:
/**
* @author a
* @version $Revision1$
*/
public class ClassA { // OK
/** */
private class ClassB {} // OK
}
/**
* @author
* @version abc
* @unknownTag value // OK, as unknown tag is allowed
*/
public class ClassC {} // OK
/** */
public class ClassD {} // OK
/** */
private class ClassE {} // OK
/** */
@Generated
public class ClassF<T> {} // OK
To configure a check that allows skipping validation at all
for classes annotated with @SpringBootApplication
and @Configuration:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocType">
<property name="allowedAnnotations" value="SpringBootApplication,Configuration"/>
</module>
</module>
</module>
Example:
/** */
@SpringBootApplication // no violations about missing param tag on class
public class Application<T> {}
/** */
@Configuration // no violations about missing param tag on class
class DatabaseConfiguration<T> {}
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.javadoc