java-doc,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

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

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

错误语法，比如没有转义的字符 ("

错误HTML，比如非法或者缺失标签或者属性的

错误引用，比如使用@see引用了不存在的类型，或者@param引用了不存在的参数

可访问性错误，比如表中缺失摘要或者标题

缺少信息，比如没有文档的参数

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

}

}

}