javadoc -Xdoclint 一直标记我的(可选)匿名类，因为它显然没有评论

Question

我正在使用 javadoc 来记录我的公共(public)枚举。我正在使用以下命令编译以下所有示例:

javac   -Xdoclint:all     LetsLearnJavadocXdoclint.java

如果我的枚举是这样的，它会生成一个没有任何警告的 .class 文件。

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A;
}

但如果我的枚举是这样的:

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A{};
}

.....我收到以下错误.....

LetsLearnJavadocXdoclint.java:4: warning: no comment
   /** Comment A. */A{};
                    ^
1 warning

考虑到我需要将评论放在其他地方，我决定在每一个可能的位置发表评论.....

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A/** Comment A. */{/** Comment A. */}/** Comment A. */;
}

……无济于事……

LetsLearnJavadocXdoclint.java:4: warning: no comment
   /** Comment A. */A/** Comment A. */{/** Comment A. */}/** Comment A. */;
                    ^
1 warning

为了绝对肯定，我走到了合乎逻辑的极端。

/** At this. */
public
/** point, I. */
enum
/** am beginning. */
LetsLearnJavadocXdoclint
/** to think. */
{
/** that I. */
   A
   /** am not. */
   {
   /** the one. */
   }
/** who is. */
   ,
/** at fault. */
   ;
/** here. */
}
/** Next question. How do I report a bug to Java? */

......还有......

$ javac -Xdoclint:all LetsLearnJavadocXdoclint.java
LetsLearnJavadocXdoclint.java:10: warning: no comment
   A
   ^
1 warning

我错过了什么吗？
为了更好地解释我的意图，我的实际目标是让这个枚举使用单个方法实现一个接口(interface)，然后让我的枚举中的每个枚举值都提供自己独特的方法实现。我一直在尝试使用 javadoc 记录它，但无济于事。这就是我想出这个最小示例的方式。
如果我不得不猜测，它可能与匿名类有关。我认为我包含的那些花括号正在创建某种形式的匿名类，它试图评论匿名类和枚举值。由于以下示例，我猜到了这一点。
如果我尝试这样做......

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   A{};
}

......我明白了......

LetsLearnJavadocXdoclint.java:4: warning: no comment
   A{};
   ^
LetsLearnJavadocXdoclint.java:4: warning: no comment
   A{};
   ^
2 warnings

2 个警告
.....这立即让我想到匿名类(class)。
显然，我不确定，但为什么会有 2 警告 除非是因为存在枚举类和它期望文档的匿名类？
最后，这是我的信息。

$ javac -version
javac 1.8.0_281

$ java -version
java version "1.8.0_281"
Java(TM) SE Runtime Environment (build 1.8.0_281-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.281-b09, mixed mode)

Answer 1

枚举常量的可选类主体隐式定义了一个匿名类声明(参见 Java Language Specification)。 Javadoc 工具不直接记录匿名类——也就是说，它们的声明和文档注释被忽略。以下匿名类示例产生相同的两个警告:

public class MyClass {

  private Runnable cleanUpOperation = new Runnable() {

    @Override
    public void run() {

    }
  };

}
对 cleanUpOperation 的缺失注释的一个警告字段和一个用于 Runnable 的匿名子类的缺失注释.
无法向匿名类添加评论。 Oracle 建议在其外部类或任何其他密切相关的类的文档注释中记录一个匿名类(详情参见 here)。因此，在您的情况下，这将是您的枚举类或枚举常量的文档注释。 -Xdoclint:all显示缺少公共(public)、 protected 、包和私有(private)成员的 javadoc 注释的警告。这也包括匿名类。
为了摆脱你的警告，你可以告诉 doclint 忽略缺少的私有(private)成员评论 -Xdoclint:all,-missing/private .执行 javac -X获取有关如何为您的目的配置 doclint 的帮助。