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

如何解决Javadoc：静态最终枚举引用的文档值 细化

假设我有：

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 做同样的 can-I-render-this-unambigiusly 吗？枚举的分析，不是吗？通过说 RHS 必须是一个单一的标识符，我们将自己限制在一些 - IMO - 应该可以明确地为 Javadoc 呈现的东西。

解决方法

正如评论已经说过的，只有当值是编译时常量时，javadoc 才会呈现它（而且很少有 - true、false、数字文字、字符串常量是它开始的地方. 所有操作数都是常量的运算符也是常量。那么任何用这样的常量初始化的静态 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 规范获得了将枚举视为编译时常量的能力（有一个显着的区别；在类级别，常量只是逐字存储在类文件中，并带有它们的实际值，而非 CTC 则不是't storage; 相反，会生成一个 static {} 块来生成这些。例如，public static final long STAMP = System.currentTimeMillis(); 被转换为一个类文件，该文件具有运行该代码的静态 init 'method' - 你不能减少到一个常量）。这是对所有 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 根本就不能那样工作。

好的，那么我如何做到这一点而不重复自己呢？

你不能。很抱歉。