在本文中,我们将看到如何使用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