javadoc -Xdoclint 一直标记我的（可选的）匿名 class 因为它显然没有评论

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

我是不是漏掉了什么？

为了更好地解释我的意图，我的实际目标是让这个枚举使用单个方法实现一个接口，然后让我的枚举中的每个枚举值提供它们自己独特的方法实现。我一直在尝试使用 javadoc 对其进行记录，但无济于事。这就是我想出这个最小示例的方式。

如果我不得不猜测，它可能与匿名 classes 有关。我认为我包含的那些大括号正在创建某种形式的匿名 class，并且它试图同时评论匿名 class 和枚举值。我猜到这是因为下面的例子。

如果我尝试这样做......

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

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

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

2 条警告

.....这让我立即想到匿名 classes.

显然，我不确定，但为什么它会有 2 WARNINGS 除非是因为有枚举 class 和匿名的 class 它期望文档来自？

最后，这是我的信息。

$ 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

枚举常量的可选 class 主体隐式定义匿名 class 声明（请参阅 Java Language Specification）。 Javadoc 工具不直接记录匿名 classes —— 也就是说，它们的声明和文档注释被忽略。以下匿名 class 示例会产生相同的两个警告：

public class MyClass {

  private Runnable cleanUpOperation = new Runnable() {

    @Override
    public void run() {

    }
  };

}

一个针对 cleanUpOperation 字段缺少注释的警告，一个针对 Runnable 的匿名子 class 缺少注释的警告。无法向匿名 class 添加评论。 Oracle 建议在其外部 class 或任何其他密切相关的 class 的文档注释中记录匿名 class（有关详细信息，请参阅 here）。因此，在您的情况下，这将是您的枚举 class 或枚举常量的文档注释。

-Xdoclint:all 显示缺少 public、protected、package 和 private 成员的 javadoc 注释的警告。这也包括匿名 classes.

要消除警告，您可以使用 -Xdoclint:all,-missing/private 告诉 doclint 忽略私人成员缺少的注释。执行 javac -X 以获得有关如何为您的目的配置 doclint 的帮助。

javadoc -Xdoclint 一直标记我的（可选的）匿名 class 因为它显然没有评论

javadoc -Xdoclint keeps flagging my (optional) anonymous class for not having a comment when it clearly does

java

warnings

javadoc

anonymous-class

2 条警告