您的“关注”和“点赞”，是认可，是支持，是动力。

如意见相佐，可留言。
本人必将竭尽全力试图做到准确和全面，终其一生进行修改补充更新。

本文首发在IT羊资源网。
《IT羊资源网》，网址：https://www.ityangzy.com
IT羊资源网是IT世界的羊群！
一个致力于科技、信息技术和计算机领域的综合在线平台。
我们的使命是为读者提供最新、全面的科技资讯、技术教程和资源下载，帮助大家在不断变化的IT领域中保持领先。
欢迎每一位志同道合的人士加入羊群！

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 工具官网主页