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

Posted 2023-03-31

【中文标题】javadoc -Xdoclint 一直标记我的（可选）匿名类，因为它显然没有评论

【英文标题】：javadoc -Xdoclint keeps flagging my (optional) anonymous class for not having a comment when it clearly does

【发布时间】：2021-07-04 17:35:05

【问题描述】：

我正在使用 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 WARNINGS 除非是因为有枚举类，以及它期待文档的匿名类？

最后，这是我的信息。

$ 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)

【问题讨论】：

另外，比我声誉更高（>1500）的人可以为这个问题添加 Xdoclint 标签吗？我觉得这可能会帮助处于类似情况的其他人，因为我可以更快地找到他们问题的答案。

【参考方案1】：

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

public class MyClass 

  private Runnable cleanUpOperation = new Runnable() 

    @Override
    public void run() 

    
  ;

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

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

要消除您的警告，您可以告诉doclint 忽略带有-Xdoclint:all,-missing/private 的私人成员丢失的cmets。执行javac -X 以获取有关如何为您的目的配置doclint 的帮助。

【讨论】：

如果无法在匿名类上添加评论，那么该工具不应该抱怨它，不是吗？

@MA 我刚刚为此向 Oracle/Java 提交了一个错误。如果有人想跟进，这里是缺陷号 (9069884)。您可以通过在此处插入该号码来跟进 - bugs.java.com/bugdatabase/index.jsp 它目前不可用，但应该在系统生成错误报告时提供。如果有任何变化，我将删除此评论并在此处更新。

@MA 这是新的错误编号 - JDK-8265253，但看起来他们立即说这不是问题 :( 不过我会提出异议，看看能不能得到它们改变主意。

@MA 他们正在重新考虑！ bugs.java.com/bugdatabase/view_bug.do?bug_id=8265253 他们还没有接受它作为他们需要修复的错误，所以我仍在战斗。但这是进步！

@MA 他们已经接受它作为一个问题并承诺修复！我们帮助改进了 Java！感谢您和 rmunge 帮助使这成为可能！ bugs.java.com/bugdatabase/view_bug.do?bug_id=8265253