Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to suppress missing javadoc checkstyle warning on enum constants/values?

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:

  1. Simple declaration which warns when both a class member or enum constant has no javadoc:

    <module name="JavadocVariable" />
    
  2. Declaration which warns when either a class member or enum constant has no javadoc:

    <module name="JavadocVariable">
        <property name="tokens" value="VARIABLE_DEF" />
    </module>
    
  3. 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>
    
like image 883
bertag Avatar asked Dec 24 '22 21:12

bertag


1 Answers

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.

like image 77
barfuin Avatar answered Dec 26 '22 10:12

barfuin