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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With