JEP 467 Markdown Documentation Comments

自 JDK 23 開始，javadoc 支援在每一行 javadoc 中，以 /// 開頭的方式，標記為markdown 格式的 javadoc，這種方式取代舊的 /** **/ ，並支援 markdown 語法。

markdown 是簡化的 html，以往在 javadoc，需要用大量的 html tag，標記為

,

, ，現在支援 markdown 語法的 標題、列表、代碼塊、連結、粗體/斜體，讓 javadoc 的內容更精簡。

新舊兩種註解寫法是同時支援的。新的 markdown，除了比較簡潔以外，解決了傳統的 javadoc 使用 html，太難寫，需要寫很多 html tag 的問題，在查看 code 裡面的註解時，markdown 的可讀性明顯比 html 高。

支援的 markdown 語法

• 粗體，斜體文字

• 段落與換行

• 有序及無序的列表 list

• 程式碼

• 標題

• 連結

• 表格

markdown javadoc 範例

    /// 這是使用 Markdown 格式的註釋。
    ///
    /// # 範例功能
    /// * 使用 **Highlight** 語法。
    ///
    /// # 程式區塊：
    /// ```java
    /// test("param");
    /// ```
    ///
    /// # 列表
    /// 1. 項目1
    /// 2. 項目2
    /// 3. 項目3
    ///
    /// # 連結 [google]("https://www.google.com")
    /// * 連結
    /// - 模組 [java.base/]
    /// - 套件 [java.util]
    /// - 類別 [String]
    /// - 欄位 [String#CASE_INSENSITIVE_ORDER]
    /// - 方法 [String#chars()]
    /// - 同一類別其他方法: [equals][#equals(Object)]
    ///
    /// # 表格
    ///
    /// | Latin | Greek |
    /// |-------|-------|
    /// | a     | alpha |
    /// | b     | beta  |
    /// | c     | gamma |
    ///
    /// @param param1 參數
    /// @return 回傳值