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 根本不能那樣工作。

好的，那么我該如何在不重復自己的情況下做到這一點？

你不能。 對於那個很抱歉。