如何抑制枚举 constants/values 上缺少的 javadoc checkstyle 警告？

Question

Checkstyle 抱怨枚举值没有附加的 javadoc 注释。但至少在我的许多枚举中，由于值本身通常是不言自明的，因此添加 javadoc 似乎只会降低可读性，并产生不必要的混乱。考虑以下示例：

/**
 * 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;

}

如果将 JavadocVariable 模块添加到我的检查中，第一个示例 (DaysOfWeekClean) 将被标记，而第二个示例 (DaysOfWeekDirty) 将通过。

这让我进退两难。我希望 checkstyle 标记未注释的正常 class members/variables，但不要理会我的枚举常量。在大量搜索 Checkstyle 文档（以及 Checkstyle 源代码本身）和几个 Whosebug 问题之后，我似乎无法弄清楚如何设置它。

当枚举常量和 class members/variables 缺少 javadoc 时，我可以发出警告，或者我可以忽略两者，但我似乎无法检查一个而不是另一个。

作为参考，这里有一些我尝试过的checkstyle配置及其结果：

当 class 成员或枚举常量都没有 javadoc 时发出警告的简单声明：
```
<module name="JavadocVariable" />
```

当 class 成员或枚举常量没有 javadoc 时发出警告的声明：

<module name="JavadocVariable">
    <property name="tokens" value="VARIABLE_DEF" />
</module>

当 class 成员或枚举常量没有 javadoc 时无法发出警告的声明：

<module name="JavadocVariable">
    <property name="tokens" value="ENUM_CONSTANT_DEF" />
</module>

Answer 1

您可以使用 SuppressionCommentFilter 或使用 @SuppressWarnings 注释从 Checkstyle 5.7 中抑制 CheckStyle 警告。

您需要对 checkstyle.xml 配置进行一些设置。

通过评论

将 SuppressionCommentFilter 添加到您的 checkstyle.xml:

<module name="SuppressionCommentFilter"/>

然后在您的代码中添加注释以关闭和重新打开 checkstyle。

//CHECKSTYLE:OFF
public enum DaysOfWeek {
    //..
//CHECKSTYLE:ON

通过注释

如果您更喜欢注释，可以使用SuppressWarningsFilter。请注意，它需要 SuppressWarningsHolder 模块。将这两个模块添加到 checkstyle.xml:

中的 TreeWalker

<module name="TreeWalker">
    <!-- make @SuppressWarnings annotations available to Checkstyle, and filter warnings by annotation
    -->
    <module name="SuppressWarningsHolder" />
    <module name="SuppressWarningsFilter" />
</module>

现在您可以用您希望排除的警告来注释您的枚举。使用适当的警告代码 & checkstyle 应该抑制它。

@SuppressWarnings("checkstyle:<appropriate warning here>")
public enum DaysOfWeek {
    //..

参考文献：

Answer 2

为了跳过枚举值，您可以像这样配置检查：

<module name="JavadocVariable">
  <property name="tokens" value="VARIABLE_DEF"/>
</module>

documentation as of 2017-01-18 is missing this information，但这已计划修复。
我用 Eclipse-CS 6.14 测试了这个行为，所以如果它不再适合你，那就是一个错误。

如何抑制枚举 constants/values 上缺少的 javadoc checkstyle 警告？

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

java

checkstyle

通过评论

通过注释