Checkstyle is complaining about enum values not having an attached javadoc comment. But at least in many of my enums, since the values themselves are often self-explanatory, adding javadoc simply seems to reduce readability with unneeded clutter. Consider the following examples:
/**
* Example enum to illustrate the problem. Each value of this
* enum represents a day of the week.
*/
public enum DaysOfWeekClean {
SUNDAY,
MONDAY,
TUESDAY,
WEDNESDAY,
THURSDAY,
FRIDAY,
SATURDAY;
}
/**
* Example enum to illustrate the problem. Each value of this
* enum represents a day of the week, with comments added to each
* distinct value to make the point.
*/
public enum DaysOfWeekCluttered {
/**
* The day of the week named "Sunday".
*/
SUNDAY,
/**
* The day of the week named "Monday".
*/
MONDAY,
/**
* The day of the week named "Tuesday".
*/
TUESDAY,
/**
* The day of the week named "Wednesday".
*/
WEDNESDAY,
/**
* The day of the week named "Thursday".
*/
THURSDAY,
/**
* The day of the week named "Friday".
*/
FRIDAY,
/**
* The day of the week named "Saturday".
*/
SATURDAY;
}
If the JavadocVariable
module is added to my checks, the first example ( DaysOfWeekClean
) will be flagged, while the second example ( DaysOfWeekDirty
) will pass.
And that leaves me in a bit of a dilemma. I want checkstyle to flag normal class members/variables which are not commented, but to leave my enum constants alone. After quite a bit of searching through the Checkstyle documentation (and the Checkstyle source code itself) and several StackOverflow questions, I can't seem to figure out how to set this up.
I can warn when javadoc is missing from both enum constants and class members/variables or I can ignore both, but I can't seem to check one and not the other.
For reference, here are some checkstyle configurations which I have tried, and their results:
Simple declaration which warns when both a class member or enum constant has no javadoc:
<module name="JavadocVariable" />
Declaration which warns when either a class member or enum constant has no javadoc:
<module name="JavadocVariable"> <property name="tokens" value="VARIABLE_DEF" /> </module>
Declaration which FAILS to warn when either a class member or enum constant has no javadoc:
<module name="JavadocVariable"> <property name="tokens" value="ENUM_CONSTANT_DEF" /> </module>
In order to skip enum values, you can configure the check like this:
<module name="JavadocVariable">
<property name="tokens" value="VARIABLE_DEF"/>
</module>
The documentation as of 2017-01-18 is missing this information , but this is planned to be fixed.
I tested this behavior with Eclipse-CS 6.14, so if it does not work for you anymore, that would be a bug.
You can suppress CheckStyle warnings with either the SuppressionCommentFilter, or from Checkstyle 5.7 by using the @SuppressWarnings annotation.
You'll need to do some setup of your checkstyle.xml configuration.
Add the SuppressionCommentFilter to your checkstyle.xml:
<module name="SuppressionCommentFilter"/>
Then add comments to your code to checkstyle off & back on.
//CHECKSTYLE:OFF
public enum DaysOfWeek {
//..
//CHECKSTYLE:ON
If you prefer annotations, you can use the SuppressWarningsFilter . Note that it needs the SuppressWarningsHolder module. Add both these modules to the TreeWalker in your checkstyle.xml:
<module name="TreeWalker">
<!-- make @SuppressWarnings annotations available to Checkstyle, and filter warnings by annotation
-->
<module name="SuppressWarningsHolder" />
<module name="SuppressWarningsFilter" />
</module>
Now you can annotate your enums with the warning you wish to exclude. Use the appropriate warning code & checkstyle should suppress it.
@SuppressWarnings("checkstyle:<appropriate warning here>")
public enum DaysOfWeek {
//..
References:
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.