【Javadoc生成开发文档（Terminal或IDEA中）】

一、Javadoc工具介绍

大家在查看官网文档的时候，会不会感慨人家的帮助文档写的真有逻辑，层次分明？

不要羡慕，你也可以！Java官方提供了Javadoc工具，便于用户自己生成项目源码配套的API开发文档，供开发人员及其他用户查看使用。该工具通过对源码中定义的类、方法、变量的特定注释信息进行提取，生成对应的开发文档。只要编码人员在源码编写时，进行合法特定的信息注释，在编码结束后即可通过Javadoc工具生成配套的开发文档。
Javadoc工具现在已经不需要单独安装了，在安装JDK的时候已经附带配置好了，大家可去自己的JDK安装路径的bin目录下查看一下，是否存在javadoc.exe，如果存在说明我们可以直接使用，如下所示：

二、常用标记

上面提到，开发人员需要以特定的注释方式进行注释，Javadoc工具才可以成功生成配套文档，那么下面这些就是所说的特定注释方式，在源码文件中我们需要使用这些标记进行注释，最后才可以被成功识别（切记Java源码中使用文档注释方式）：

标签	说明
@author 作者	作者标识
@version 版本号	版本号
@param 参数名	描述方法的入参名及描述信息，如入参有特别要求，可在此注释。
@return 描述	对函数返回值的注释
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。
@throws异常类名	构造函数或方法所会抛出的异常。
@throws异常类名	构造函数或方法所会抛出的异常。
@exception 异常类名	同@throws。
@see 引用	查看相关内容，如类、方法、变量等。
@since 描述文本	API在什么程序的什么版本后开发支持。
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。

更多可查看官方文档。

三、使用方式

javadoc [选项] [java包名] [java源文件名]

其中常用选项如下图所示，大家不用记，需要时直接在本地Terminal中输入

javadoc -help

命令，就会出现如下所示的帮助信息，大家根据需要添加相应的选项即可。

当然，使用上述命令的前提是大家已经在自己本机中配置好了JDK的环境变量，因为上面提过javadoc.exe文件是在JDK安装目录的bin目录下的，如果没有配置环境变量，这里会提示该命令不存在的错误。

四、生成文档的两种方式

到这里，我已具体实例操作展示两种生成开发文档的过程：
对应文件内容如下：

1.Terminal方式

Terminal方式其实使用的很少了，毕竟现在各种IDE已经应用的很成熟，很多工作都是一键完成，这里还是简单介绍一下这种方式，大家了解即可：
1）打开本地Terminal（Win+R输入cmd即可）：

2）进入源码对应的包（package）：

3）输入javadoc命令生成开发文档即可（该文档会默认在当前目录下生成）：
这里直接生成一个软件包对应的开发文档，也可直接生成单个java源文件的开发文档，此时需要进入到该源文件所在文件目录下。

生成结果如下：

使用浏览器打开此处的任意html文件，即可查看本项目对应的开发文档：

默认只会识别公共类、公共方法对应的注释信息，如果需要调整显示所有类、所有方法可通过第三节中提到的“选项 -private”进行设置。

4）解决中文乱码问题
此处需特别说明，如果源码中包括中文注释信息，在生成文档中可能会发生中文乱码的现象，我们可通过如下命令去解决，其实还是采用javadoc 命令中的编码选项：

javadoc -encoding UTF-8 -charset UTF-8 [包名] [源文件]

如此，在生成的开发文档中则不会发生乱码现象了：

2.IDE方式

热门的Java开发IDE当属IDEA，下面介绍一下IDEA中如何生成开发文档：
1）光标选中想要生成对应文档的目录或者文件，然后依次点击Tools->Generate JavaDoc：

打开界面如下所示，在这里可进行开发文档输出目录、注释信息识别范围等选择：
注意此处输出目录建议选择“绝对路径”

对应生成结果与Terminal方式一样，大家自行测试即可：