如何抑制枚举常量/值上缺少的javadoc checkstyle警告? [英] How to suppress missing javadoc checkstyle warning on enum constants/values?

问题描述

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

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;

}

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

If the JavadocVariable module is added to my checks, the first example (DaysOfWeekClean) will be flagged, while the second example (DaysOfWeekDirty) will pass.

这让我陷入了两难的境地.我希望checkstyle标记未评论的普通类成员/变量，而让我的枚举常量不予理会.在仔细检查了Checkstyle文档(以及Checkstyle源代码本身)和几个StackOverflow问题之后，我似乎无法弄清楚如何进行设置.

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.

两个枚举常量和类成员/变量中都缺少javadoc时，我可以发出警告，或者我可以忽略两者，但似乎无法同时检查其中一个.

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.

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

For reference, here are some checkstyle configurations which I have tried, and their results:

1. 简单声明，当类成员或枚举常量都没有javadoc时发出警告:

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

<module name="JavadocVariable" />

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

Declaration which warns when either a class member or enum constant has no javadoc:

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

声明当类成员或枚举常量中没有javadoc时警告哪些失败:

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>

截至2017年1月18日的文档是

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.

这篇关于如何抑制枚举常量/值上缺少的javadoc checkstyle警告?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！