Javadoc

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')
      }
    }
  }

推荐阅读更多精彩内容