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

JEP 172: DocLint

提供了一种早期开发阶段检测到javadoc注释错误的方法，并且可以链接到源代码。

以下几种错误将被检测到：

1. 错误语法，比如没有转义的字符 ("<")或者不匹配的括号("{@foo")
2. 错误HTML，比如非法或者缺失标签或者属性的
3. 错误引用，比如使用@see引用了不存在的类型，或者@param引用了不存在的参数
4. 可访问性错误，比如表中缺失摘要或者标题
5. 缺少信息，比如没有文档的参数

相对规范比较严格，旨在获得符合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')
      }
    }
  }