javadoc 注释_在Javadoc注释中使用Markdown语法

javadoc 注释

在本文中，我们将看到如何使用Markdown而不是典型的Javadoc语法编写Javadoc注释。

那么，Markdown是什么？

Markdown是一种纯文本格式语法，旨在使它可以选择使用相同名称的工具转换为HTML。 Markdown通常用于格式化自述文件，在在线讨论论坛中或在文本编辑器中编写消息以快速创建RTF文档。
（维基百科： Markdown ）

Markdown是一种非常易于阅读的格式语法。 Markdown的不同变体可以在Stack Overflow或GitHub上使用，以格式化用户生成的内容。

建立

默认情况下，Javadoc工具使用Javadoc注释生成HTML格式的API文档。 这个过程可以定制使用
Doclets 。 Doclet是Java程序，用于指定Javadoc工具输出的内容和格式。

markdown-doclet替代了标准Java Doclet，它使开发人员可以选择在其Javadoc注释中使用Markdown语法。 我们可以使用maven-javadoc-plugin在Maven中设置此doclet。

<build>
  <plugins>
    <plugin>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9</version>
      <configuration>
        <doclet>ch.raffael.doclets.pegdown.PegdownDoclet</doclet>
        <docletArtifact>
          <groupId>ch.raffael.pegdown-doclet</groupId>
          <artifactId>pegdown-doclet</artifactId>
          <version>1.1</version>
        </docletArtifact>
        <useStandardDocletOptions>true</useStandardDocletOptions>
      </configuration>
    </plugin>
  </plugins>
</build>

在Markdown中撰写评论

现在我们可以在Javadoc注释中使用Markdown语法：

/**
 * ## 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我们可以在target / site / apidocs中找到生成HTML API文档。

上面显示的方法生成的文档如下所示：

如我们所见，Javadoc注释可以很好地转换为HTML。

结论

与标准Javadoc语法相比，Markdown具有明显的优势，即源代码更容易阅读。 请看一下java.util.Map的一些方法注释。 许多Javadoc注释都带有格式标记，并且几乎没有任何工具就无法读取。 但是请注意，Markdown可能会导致期望标准Javadoc语法的工具和IDE出现问题。

翻译自: https://www.javacodegeeks.com/2014/06/using-markdown-syntax-in-javadoc-comments.html

javadoc 注释