Javadoc：static 最终枚举参考的文档值

Question

假设我有：

public enum Color {
    RED,
    GREEN,
    YELLOW
}

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

public static final Color DEFAULT_COLOR = Color.RED;

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

show up in Javadoc's "constant-values.html".问题是 - 如我所见 - 这样的引用（虽然声明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 字段本身就是常量。因此， 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 规范获得了将枚举视为编译时间常量的能力（存在显着差异；在 class 级别，常量只是逐字存储，其实际值在 ZA2F2ED4F8EBTCAB6CBB4C21A2D 文件中存储，而非 CDC ; instead a static {} block is generated that generates these. For example, public static final long STAMP = System.currentTimeMillis(); is turned into a class file that has a static init 'method' that runs that code - you can' t 减少到一个常数）。 这是对所有 java 的相当大的更新，只是为了 javadoc，这很奇怪。
• 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 根本不能那样工作。

好的，那么我该如何在不重复自己的情况下做到这一点？

你不能。 对于那个很抱歉。