Javadoc
[TOC]
Javadoc标签
| 标签&参数 | 用途 | 适用于 | 引入版本 |
|---|---|---|---|
| @author John Smith | 描述作者 | 类、接口、枚举 | |
| {@docRoot} | 表示从任何生成的页面生成的文档的根目录的相对路径。 | 类、接口、枚举、成员、方法 | |
| @version 版本 | 提供软件版本，每个类或接口最多一个。 | 类、接口、枚举 | |
| @since 起始 | 描述此功能首次存在的时间。 | 类、接口、枚举、成员、方法 | |
| @see 参考 | 提供指向其他文档元素的链接。 | 类、接口、枚举、成员、方法 | |
| @param 名称 描述 | 描述方法的一个参数。 | 方法 | |
| @return 描述 | 描述返回值。 | 方法 | |
| @exception 类 描述 | 描述可能从此方法抛出的异常。 | 方法 | |
| @throws 类 描述 | 描述可能从此方法抛出的异常。 | 方法 | |
| @deprecated 描述 | 描述一个过时的方法。 | 类、接口、枚举、成员、方法 | |
| {@inheritDoc} | 从被覆盖的方法复制描述。 | 覆盖方法 | 1.4.0 |
| {@link 参考} | 链接到其他符号。 | 类、接口、枚举、成员、方法 | |
| {@linkplain 参考} | 与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。 | 类、接口、枚举、成员、方法 | |
| {@value #STATIC_FIELD} | 返回静态成员的值。 | 静态成员 | 1.4.0 |
| {@code 文本} | 在代码字体中格式化文字文本，等同于<code> {@literal} </code>。 | 类、接口、枚举、成员、方法 | 1.5.0 |
| {@literal 文本} | 表示文本，随附的文本被解释为不包含HTML标记或嵌套的javadoc标记。 | 类、接口、枚举、成员、方法 | 1.5.0 |
| {@serial 文本} | 在Javadoc注释中用于默认的可序列化字段。 | 成员 | |
| {@serialData 文本} | 记录writeObject()或writeExternal()方法写入的数据。 | 成员、方法 | |
| {@serialField 文本} | 记录ObjectStreamField组件。 | 成员 |
DocLint
提供了一种早期开发阶段检测到javadoc注释错误的方法，并且可以链接到源代码。
以下几种错误将被检测到：
- 错误语法，比如没有转义的字符 ("<")或者不匹配的括号("{@foo")
- 错误HTML，比如非法或者缺失标签或者属性的
- 错误引用，比如使用@see引用了不存在的类型，或者@param引用了不存在的参数
- 可访问性错误，比如表中缺失摘要或者标题
- 缺少信息，比如没有文档的参数
相对规范比较严格，旨在获得符合W3C HTML 4.01标准规范的HTML文档。如果违反这些规则，将不会得到javadoc的输出。
工具将扫描源文件，查找关联javadoc注释的声明。使用DocTree API解析这些注释，然后分析结果AST（抽象语法树），寻找问题。
关闭DocLint
严格的规范导致在JDK8中生成javadoc失败，对于已有代码的文档，可以选择关闭DocLint，不过如果是新代码，尽量按照规范写文档。
Maven
maven-javadoc-plugin版本3.0.0以及以上：
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<!-- Turnoff all checks -->
<doclint>none</doclint>
</configuration>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
maven-javadoc-plugin版本3.0.0以下：
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<!-- Turnoff all checks -->
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
<!-- executions.... -->
</plugin>
</plugins>
Gradle
if (JavaVersion.current().isJava8Compatible()) {
allprojects {
tasks.withType(Javadoc) {
options.addStringOption('Xdoclint:none', '-quiet')
}
}
}
