文章目录
- 1 Javadoc 概述
- 2 Javadoc 标签
- 3 Javadoc 命令
- 4 使用 Javadoc 生成 API 文档
- 4.1 DOS 命令生成 API 文档
- 4.2 Eclipse 生成 API 文档
- 【参考资料】
- [Oracle 官网](https://www.oracle.com/)
- [Javadoc 工具官网主页](https://www.oracle.com/java/technologies/javase/javadoc-tool.html)
1 Javadoc 概述
Java 支持三种注释，分别是单行注释、多行注释和文档注释，单行注释、多行注释和文档注释详解请参见文章《Java 注释》，本文主要详解 Javadoc（Java API 文档生成器）。
Java 文档注释是用来生成 API 文档的。Java 文档注释以/**开始，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、接口、方法、成员变量、构造器和内部类。
Javadoc （Java API 文档生成器）是一种从源代码中的文档注释生成 HTML 格式的 API 文档的工具。
Javadoc 是 Sun 公司提供的一种工具，它只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时在文档注释中以一套特定的标签（请参见后面 2 Javadoc 标签）注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档。API 帮助文档相当于产品说明书，说明书只需要介绍那些供用户使用的部分，所以 javadoc 工具默认只会处理以 public 或 protected 修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释。如果要提取 private 修饰的部分，需要使用 -private。
2 Javadoc 标签
Javadoc 工具在嵌入 Java 文档注释中时解析特殊标签。这些 doc 标签使您能够从源代码自动生成完整的、格式良好的 API。标签以@开头，并且区分大小写——它们必须使用大写和小写字母输入。标签必须在行首开始，否则将被视为普通文本。按照惯例，具有相同名称的标签被组合在一起。例如，将所有 @see标签放在一起。
标签有两种类型：
- 块标签：只能放置在主要描述后面的标签部分。块标记的形式为：
@tag。 - 内嵌标签：可以放置在主要描述或块标记的注释中的任何位置。内联标签用花括号表示：
{@tag}。
Javadoc 可以识别的标签 如下表所示：
标签 | 描述 | 在 JDK/SDK 中引入 |
@author | 名称文本，仅限类和接口 | 1.0 |
{@code} | 显示文本，而不会将文本解释为 HTML 标记或嵌套的 javadoc 标签 | 1.5 |
{@docRoot} | 指明当前文档根目录的路径 | 1.3 |
@deprecated | 弃用文本，指名一个过期的类或成员，表明该类或方法不建议使用 | 1.0 |
@exception | 可能抛出异常的说明，一般用于方法注释 | 1.0 |
{@inheritDoc} | 从直接父类继承的注释 | 1.4 |
{@link} | 插入一个到另一个主题的链接 | 1.2 |
{@linkplain} | 插入一个到另一个主题的链接，但是该链接显示纯文本字体 | 1.4 |
{@literal} | 显示文本，而不会将文本解释为 HTML 标记或嵌套的 javadoc 标签 | 1.5 |
@param | 说明一个参数，仅限方法和构造器 | 1.0 |
@return | 说明返回值类型，仅限方法 | 1.0 |
@see | 指定一个到另一个主题的链接 | 1.0 |
@serial | 说明一个序列化属性 | 1.2 |
@serialData | 说明通过 writeObject() 和 writeExternal() 方法写的数据 | 1.2 |
@serialField | 说明一个 ObjectStreamField 组件 | 1.2 |
@since | 说明从哪个版本起开始有了这个函数 | 1.1 |
@throws | 和 @exception 标签一样. | 1.2 |
{@value} | 显示常量的值，该常量必须是 static 属性。 | 1.4 |
@version | 指定版本，仅限类和接口 | 1.0 |
3 Javadoc 命令
javadoc 命令语法格式如下：
javadoc [options] [packagenames] [sourcefilenames] [-subpackages pkg1:pkg2:...] [@argfiles]说明：
- options：表示 javadoc 命令选项。如何查看 javadoc 的用法和选项，请参见后面介绍。
- packagenames：表示包名。一系列包的名称，以空格分隔，如 java.lang java.lang.reflect java.awt. 必须单独指定要记录的每个包。不允许使用通配符；使用 -subpackages 进行递归。Javadoc 工具用于 -sourcepath 查找这些包名称。
- sourcefilenames：表示源文件名。
- -subpackages pkg1:pkg2:…：从指定包中的源文件并在其子包中递归生成文档。
- @argfiles：一个或多个文件，其中包含以任何顺序排列的 Javadoc 选项、包名和源文件名列表。
在 CMD （命令提示符）中查看 javadoc 的用法和选项：
javadoc -help
4 使用 Javadoc 生成 API 文档
4.1 DOS 命令生成 API 文档
第一步：新建一个名为Test.txt的空白记事本，输入以下代码，
/**
* @author 码农阿杰
* @version 1.0
*/
public class Test {
/**
* 求输入两个参数的和
*
* @param m 接收的第一个参数
* @param n 接收的第二个参数
* @return 两个参数的和
*/
public static int add(int m, int n) {
return m + n;
}
}第二步：将文件扩展名改为.java，即改后为Test.java。
第三步：在Test.java文件所在的目录中打开 cmd 窗口，命令如下所示，
-
javadoc -author -version Test.java命令，此命令没有考虑编码格式问题，注释中有汉字可能会乱码。 javadoc -encoding UTF-8 -charset UTF-8 Test.java命令可以解决编码问题。
输入命令后，按回车键，等待生成文件。Test.java文件所在的目录中将会生成Test.html文档文件，打开如下图所示：
4.2 Eclipse 生成 API 文档
第一步：在 Eclipse 中新建一个 Test 类，代码如下，
package com;
/**
* @author 码农阿杰
* @version 1.0
*/
public class Test {
/**
* 求输入两个参数的和
*
* @param m 接收的第一个参数
* @param n 接收的第二个参数
* @return 两个参数的和
*/
public static int add(int m, int n) {
/**
* 这是一个输出语句
*/
return m + n;
}
}注意：return 语句上面那个文档注释将会被 javadoc 忽略，因为没有放在类、成员变量或方法之前。
第二步：利用 Eclipse 自身的功能生成帮助文档，步骤如下所示，
（1）选中项目名，右键，选中“Export”，如下图所示：
（2）点击“Export”，在弹出的界面中找到“Java”目录，在 Java 目录中选中“Javadoc”，如下图所示：
（3）点击“Next”，在弹出的界面中选择你要生成 Javadoc 的项目及保存路径（默认是工程路径，建议不改），再点击“Finish”，如下图所示：
（4）点击“Finish”后，会弹出询问是否更新 Javadoc 文件位置的对话框，点击“Yes To All”即可，如下图所示：
（5）此时可以在控制台看到有输出生成 Javadoc 的信息，如下图所示：
（6）根据（3）步骤中所设置的保存文档的路径，找到Test.html文件并打开，如下图所示：
Oracle 官网
Javadoc 工具官网主页
