翻譯：在 Javadoc 註解中使用 Markdown 語法

在 Javadoc 註解中使用 Markdown 語法

在這篇文章中，我們將了解如何使用 Markdown而不是標準 Javadoc 語法來編寫 Javadoc 註解。那什麼是 Markdown 呢？Markdown 是一種簡單的標記語言，可以選擇使用同名工具將其翻譯為 HTML。Markdown 廣泛用於格式化自述文件、編寫論壇帖子以及在文字編輯器中快速創建漂亮的文本文檔。（維基百科：Markdown）Markdown 格式的文字非常容易閱讀。Stack Overflow 或 GitHub 上使用各種風格的 Markdown 來格式化使用者產生的內容。

安裝

預設情況下，Javadoc 工具使用 Javadoc 註解來產生 HTML 形式的 API 文件。可以使用Doclets重新配置此程序。Doclet 是指定 Javadoc 工具輸出檔案的內容和格式的 Java 程式。 Markdown-doclet 取代了標準的 Java Doclet，從而使開發人員能夠在其 Javadoc 註解中使用 Markdown 語法。您可以使用 maven-javadoc-plugin 將其安裝在 Maven 中。 maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

在 Markdown 寫評論

現在您可以使用 Markdown 語法編寫 Javadoc 註解： /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } 執行後

mvn javadoc:Javadoc

產生的 HTML API 文件位於

目標/網站/apidocs。

上述程式碼產生的文件如下所示： 從圖中可以看到，Javadoc註解完美轉換為HTML。

結論

Markdown 與標準 Javadoc 語法相比有一個明顯的優勢：它更容易在原始程式碼中閱讀。只要看一下 java.util.Map 中的一些方法註解即可：其中許多都充滿了格式化標籤，如果不使用其他工具很難閱讀。但您需要記住，Markdown 可能會導致只能使用標準 Javadoc 語法的工具和 IDE 出現問題。資料來源：在 Javadoc 中使用 Markdown 語法評論來自我們的JCG 合作夥伴Michael Scharhag ，來自 mscharhag 部落格「Programming and Stuff」。