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

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

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 可以识别的标签 如下表所示：

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