Javadoc生成开发文档
- 一、Javadoc工具介绍
- 二、常用标记
- 三、使用方式
- 四、生成文档的两种方式
- 1.Terminal方式
- 2.IDE方式
一、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方式一样，大家自行测试即可：
