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>
   

回答1:

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.

回答2:

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.

By Comments

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

By Annotations

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:

• http://checkstyle.sourceforge.net/config_filters.html#SuppressionCommentFilter
• http://checkstyle.sourceforge.net/config_filters.html#SuppressWarningsFilter
• https://stackoverflow.com/a/4023351/768795
• https://stackoverflow.com/a/22556386/768795

来源：https://stackoverflow.com/questions/41709418/how-to-suppress-missing-javadoc-checkstyle-warning-on-enum-constants-values