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

编程问答 2022-05-14

问题描述

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

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 记录它，但无济于事。这就是我想出这个最小例子的原因。

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

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

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

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

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

2 个警告

.....这让我立刻想到了匿名类。

显然，我不确定，但为什么它会有 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)

解决方法

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

public class MyClass {

  private Runnable cleanUpOperation = new Runnable() {

    @Override
    public void run() {

    }
  };

}

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

-Xdoclint:all 显示公共、受保护、包和私有成员缺少 javadoc 注释的警告。这也包括匿名类。

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

anonymous-classjavajavajavadocjavadocwarnings