翻译：在 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”。