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 文本}	在代码字体中格式化文字文本，等同于 {@literal} 。	类、接口、枚举、成员、方法	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以及以上：

  
    org.apache.maven.plugins
    maven-javadoc-plugin
    3.1.1
    
      
      none  
    
    
      
        attach-javadocs
        
          jar
        
      
    
  

maven-javadoc-plugin版本3.0.0以下：

  
    org.apache.maven.plugins
    maven-javadoc-plugin
    
      
      -Xdoclint:none  
    
    
  

Gradle

 if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
      tasks.withType(Javadoc) {
        options.addStringOption('Xdoclint:none', '-quiet')
      }
    }
  }