Javadoc：静态最终枚举引用的文档值

Question

假设我有：

public enum Color {
    RED,
    GREEN,
    YELLOW
}

然后在我的代码中的其他地方

public static final Color DEFAULT_COLOR = Color.RED;

现在我想向我的 Javadoc 的读者记录DEFAULT_COLOR 的价值是什么（当然，我不再重复自己）。该怎么做？

问题在于——正如我所见——这样的引用（尽管声明为static final 并指向一个枚举）将不会显示在Javadoc 的“constant-values.html”中。我看不出它不应该的技术原因，但据我所知，它不应该。也许我只是误解了？

细化

确切地说，问题是关于 Enum 变量的 static final 声明，其中右侧是 JLS 定义的单个标识符，因此不包括 RHS 是更复杂表达式的情况。这类似于当前用于原始类型分配的 Javadoc 行为，如果 RHS 不是所谓的“常量表达式”，Javadoc 将不会尝试呈现。我们当然可以期待 Javadoc 做同样的事情，我可以毫无疑问地渲染这个吗？枚举分析，不是吗？通过说 RHS 必须是单个标识符，我们将自己限制在 IMO 应该可以明确地为 Javadoc 呈现的东西。

Answer 1

正如评论已经说过的，只有当值是编译时常量时，javadoc 才会渲染它（很少有东西是 - true，false，数字文字，字符串常量是它开始的地方。所有的运算符操作数是常量也是常量。那么任何用这样的常量初始化的静态最终字段本身就是常量。因此，static final int foo = SOME_OTHER_FIELD + YET_ANOTHER + 5; 可以是常量。

这意味着 Color.RED 不是常数，因此不会显示。

这不仅仅是“解决问题”的问题，而是渲染的问题。

想象一下你是这样写的：

private static final List<String> COUNTRIES = List.of(... all 300-or-so countries here_);

是否应该将整个列表注入到 javadoc 中？希望这个例子清楚地表明答案并不总是“是”，画一条线也不是真的可行。

即使答案是肯定的，您如何建议 javadoc 呈现此信息？只需获取原始源代码并将其直接转储到 html 中？获取原始源代码并自动重新格式化它？还有哪些其他选择？

Javadoc 不能假设它可以解析表达式。想象一下表达式是：

public static final Color DEFAULT_COLOR = Math.random() > 0.5 ? Color.RED : Color.BLUE;

这应该清楚地表明，除了显示应用了某种程度的清理的源或什么都不显示之外，您没有任何可行的选择来呈现非 CTC。

您可能想看到的是：

• JVM 规范获得了将枚举视为编译时常量的能力（存在显着差异；在类级别，常量只是逐字存储在类文件中，以及它们的实际值，而非 CTC '不存储；而是生成一个 static {} 块来生成这些。例如，public static final long STAMP = System.currentTimeMillis(); 被转换为一个类文件，该类文件具有运行该代码的静态 init '方法' - 你不能将其减少到一个常量)。只是为了 javadoc 的利益，这是对所有 java 的一个相当大的更新，这很奇怪。
• javadoc 工具与 JVM 规范分道扬镳，在 CTC 上独树一帜。这似乎很烦人。当然，您希望 public static final Color DEFAULT_COLOR = SomeOtherClass.DEFAULT_COLOR; 也能正常工作（如果它们是整数，它会工作！），这使得 javadoc 复杂且不一致。只是不值得。
• 一个选项告诉 javadoc 只获取初始化程序的源代码并将其逐字呈现（或者通过重新格式化的简单应用程序，也许）到 HTML 中。

第三个看起来很公平，类似于：

/** {@showDefault} */
public static final Color DEFAULT_COLOR = Color.RED;

但是 javadoc 根本不能那样工作。

好的，那我该如何做而不重复自己呢？

你不能。对此感到抱歉。