1. 简介
官网：Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.
译：Javadoc是一款能根据源代码中的文档注释来产生HTML格式的API文档的工具。
解释：只要你在java源码中按一定的格式写注释，就可以利用 Javadoc 这款工具自动生成配套的API文档。
文档注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。
文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。所以，虽然有些标记写起来麻烦且看着不直观，还是要老老实实按规矩写滴。
2. Javadoc 的组成
一个文档注释由两部分组成：
/**
* 描述部分(description)
*
* 标记部分(block tags)
*/
描述部分自然不用多说，所谓的标记符号指的是@param，@return，@see之类的。需要注意的是描述部分和文档标记之间必须空一行，描述段落必须在标记段落之前
3. Javadoc 的使用规范
所有 Public 和 Protected 方法都应当有相应的 Javadoc。Package 和 Private 方法不强求，但是如果有帮助的话加上也很好
Javadoc 以 /** 开头、以 */ 结尾，并且每行要以星号开头：
/**
* Standard comment.
*/
public ...
Javadoc要和其后对应的类/方法/字段/包保持同样的缩进，以下例子就是错误的
class student {
/**
* 没有和下面的方法保持同样的缩进，是错误的.
*/
public int getName(int ID){
...
}
}
3.1. 描述部分(Description)
首句很重要
Javadoc 的首句（用英文句号结束）也被作为这个 Javadoc 的摘要，在折叠的时候只会显示这一句。因此首句必须是个总结性的描述，它最好简洁有力，不能太长
用单个 <p> 来分割段落
Javadoc 经常会需要分成好几段。所以问题来了：怎样优雅地加上段落标记？答案是，在两段之间写上一行 <p> 就可以了，不用加 </p> 闭合它
/**
* First paragraph.
* <p>
* Second paragraph.
* May be on multiple lines.
* <p>
* Third paragraph.
*/
public ...
用单个 <li> 来标记列表项
列表在 Javadoc 中也很常用，比如用来表示一组选项、一些问题等等。推荐的做法是用一个 <li> 作为每项的开头，同样不需要闭合。此外，别忘了加段落 tag
/**
* First paragraph.
* <p><ul>
* <li>the first item
* <li>the second item
* <li>the third item
* </ul><p>
* Second paragraph.
*/
public ...
3.2. 标记部分(Tag)
下面是常见的文档标记
@author 作者名（只出现在类和接口的文档中）
@version 版本号（只出现在类和接口的文档中）
@param 参数名（只出现在方法或构造器的文档中）
@return 返回值情况（只出现在方法中）
@throws 异常抛出情况
@exception @throws 和 @exception是一模一样的
@see
@since 指明需要最早使用的jdk版本
@serial（也可以使用@serialField或@serialData替代）
@deprecated 给出代码被弃用的原因、何时可能被弃用以及替代方案的解释
@value 常用于写在字段上的Javadoc注释
如果方法有参数，@param标记必须包含，而且每个对应一个参数 如果方法有返回值，@return标记必须包含
在IDEA中，可以安装Easy JavaDoc 插件快速生成
4. 用IDE生成
IDEA工具栏中选择Tools——>Generate JavaDoc
- 第一步：选择生成JavaDoc文档的范围，我只对一个源文件生成Doc，所以选择文件。
- 第二步：输出目录最好新建一个文件夹，比较有条理和整洁
- 第三步：区域设置，决定文档的语言，简体中文就是zh_CN、繁体(台湾)zh_tw、繁体(香港)zh-hk、英语(香港)en-hk、英语(美国)en-us、英语(英国)en-gb、英语(全球)en-ww
- 第四步：其他命令行参数：如果区域设置为中国，参数一般为
-encoding UTF-8 -charset UTF-8 - 第五步：设置完成后点击确定即可生成Doc文档
打开输出目录，就可看到成功生成，打开 index.html 便能看生成的文档。
