javadoc 生成 API 文档

javadoc 生成 API 文档

javadoc 是什么

javadoc是 JDK 中自带的一个很有用的工具,它从源代码中抽取类、构造器、方法、字段等注释形成一个和源代码配套的 API 帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过 javadoc 工具就可以同时形成程序的开发文档了。

Java 中有 3 种注释方法:
1) // ...:单行注释
2) /* ... */:多行注释
3) /** ... */:多行注释

其中第三种是专门为 javadoc 设计的,它可以被 javadoc 解析为相应的 HTML 文档,javadoc 官方文档
如果你经常查阅Java API - Oracle 官方文档,你会发现,这个庞大的在线 API 文档其实就是使用 javadoc 工具生成的。

文档注释格式

文档注释的位置
(package-info.java)、接口构造器方法属性

文档注释的三部分
1) 简述:简述位于注释的起始位置,直到出现第一个.句号(包括句号);
2) 详细说明:详细说明包括简述,对格式没有特别要求,可以有若干个句号;
3) 标记部分:所有的标记都以@开头,包括版本说明、参数说明、返回值说明等。

在 javadoc 注释中可以使用 HTML 标签,比如:换行不应该直接敲入一个回车,而应使用标签<br>;起一个段落应使用标签<p>放在段落的起始位置。

@块标记
常用的块标记有:
1) @author 作者:用于包、类、接口,可以有多个;
2) @version 版本号:用于包、类、接口;
3) @since JDKx.x:支持的 JDK 版本,用于包、类、接口、构造器、方法、属性;
4) @param 参数名 描述:形参的说明,用于构造器、方法;
5) @return 描述:函数返回值的说明,用于方法;
6) @throws 异常类名 描述:可能会抛出的异常说明,用于构造器、方法;
7) @exception 异常类名 描述:同@throws标记;
8) @deprecated 描述:对已过期 API 的描述,用于包、类、接口、构造器、方法、属性;
9) @see 包.类#字段/方法(param...):如果跳转的 url 就是当前类的其他方法/字段,则#之前的可以省略,用于包、类、接口、构造器、方法、属性;
10) {@link 包.类#字段/方法(param...)}:同@see标记;
11) {@value 包.类#字段}:引用 final 常量的值,用于 final 属性;
12) {@code text}:不进行 HTML 解析,表示一个纯文本的代码;
13) {@inheritDoc}:从继承的类、接口中继承注释,可以进行拼接,参数、返回值、异常可以在子类中覆盖父类的相关注释。

常用 HTML 标签:
1) <br>:换行标签
2) <p>:段落标签
3) <blockquote><pre> ... </pre></blockquote>:多行代码块
4) <strong> ... </strong>:粗体强调
5) <em> ... </em>:斜体强调
6) <b> ... </b>:显示粗体
7) <i> ... </i>:显示斜体

javadoc 命令

javadoc 命令

常用命令选项
-public:只显示 public 类、成员
-protected:只显示 protected/public 类、成员(默认)
-package:只显示 package/protected/public 类、成员
-private:显示所有类、成员

-sourcepath <pathlist>:指定源代码文件搜索路径
-classpath <pathlist>:指定用户类文件搜索路径
-cp <pathlist>:指定用户类文件搜索路径(同 -classpath)
-exclude <pkglist>:指定要排除的 package 包
-subpackages <subpkglist>:指定递归加载的子 package 包

-verbose:输出详细信息
-quiet:输出简略信息

-locale <name>:指定生成的文档的语言环境(必须位于所有选项的前面),如 en_US、zh_CN
-encoding <name>:指定源代码文件使用的字符编码,如 UTF-8、GBK、GB2312

标准 doclet 参数
-d <directory>:输出文件的存放目录

-version:包含@version字段
-author:包含@author字段
-serialwarn:生成有关@serial标记的警告
-use:创建类和 package 的用法页面

-nodeprecated:不包含@deprecated字段
-nosince:不包含@since字段

-nodeprecatedlist:不生成已过时的 API 列表
-nocomment:不生成说明和标记,只生成声明
-notimestamp:不包含隐藏时间戳
-notree:不生成类分层结构
-noindex:不生成索引
-nohelp:不生成帮助链接
-nonavbar:不生成导航栏

-windowtitle <text>:指定文档的 title 标题
-docencoding <name>:指定生成的 HTML 文档的字符编码

典型用法举例

javadoc 例子
1) 创建两个 package 包:com.zfl9.test1、com.zfl9.test2;
2) 在每个 package 包中创建一个 package-info.java 包描述文件。

因为两个包的内容很相似,所以这里只做 com.zfl9.test1 包的演示。

package-info.java

Test.java

生成文档并部署

浏览一下效果:
javadoc 效果 - 1
javadoc 效果 - 2
javadoc 效果 - 3
javadoc 效果 - 4