一、说明
- 文档注释(Java Doc Comments)是指允许你在程序中嵌入关于程序的信息，使你更加方便的记录你的程序的信息
- 你可以使用Javadoc工具软件来生成信息，并输出到HTML文件中
- Generate JavaDoc 是 Sun公司提供的一种工具，它可以从程序源代码中抽取类、方法、成员等注释，形成一个和源代码配套的 API 帮助文档
二、理解
- Java支持三种注释方式
// 这是一般注释 /* * 这是一般注释 */ /** * 这是文档注释 */
- 一个文档注释由描述部分和标记部分两部分组成
- 文档注释第一行以特殊的文档定界符 /** 开头，描述部分和标记部分必须分开，且描述段落必须在标记段落之前，每一行注释都应该保持同样距离的缩进
/** * 描述部分(description) 用来描述类和方法的功能特点等 * * 标记部分(block tags) 用于描述标签 */
public interface Executor { /** * Executes the given command at some time in the future. The command * may execute in a new thread, in a pooled thread, or in the calling * thread, at the discretion of the {@code Executor} implementation. * * @param command the runnable task * @throws RejectedExecutionException if this task cannot be * accepted for execution * @throws NullPointerException if command is null */ void execute(Runnable command); }
- Javadoc 标签
| 标签 | 描述 | 说明与示例 |
| @author | 标识类的作者 | 只能用在类的标记文档中@author description |
| @version | 标志类的版本 | 只能用在类的标记文档中@version info |
| @param | 标志方法的参数 | 只能用在方法标记文档中@param parameter-name explanation |
| @return | 标志返回值类型 | 只能用在方法标记文档中@return explanation |
| @exception | 标志一个类抛出的异常 | @exception exception-name explanation |
| @throws | 标志方法或类抛出的异常 | @throws NullPointerException if command is null |
| @see | 引用其他类中的文档 | @see anchor |
| @since | 标志这个方法或类在哪个版本时添加的 | @since release |
| @deprecated | 标志一个过期的类或成员 | 在代码中使用被@deprecated标记的方法会收到编译器的警告@deprecated description |
- 类文档标记中的标记部分中要按照@param、@return、@throws、@since、@see、@deprecated的顺序进行排列，@return后说明返回值类型，而没有返回变量名
三、实现
通过 Intellij IDEA 自带的 Generate JavaDoc 功能，可以自动生成文档注释
Generate JavaDoc scope生成文档范围
Whole project整个项目
File '....src\com\.....当前文件
Custom scope自定义范围
lnclude JDK and library sources in -sourcepath包含JDK和第三方库
link to JDK documentation链接到JDK文档，即API
output directy生成文档存放的位置
private、package、protected、public生成文档的级别，即类和方法
@use等是指生成文档包含的内容信息
Generate hierarchy tree包含层级树
Generate navigation bar包含导航
Generate index包含索引
Separate index per letter每个字母的单独索引
Locale语言类型，一般设置为zh-CN
Other command line arguments其它命令参数，一般用于设置统一文件编码与字符集-encoding UTF-8 -charset UTF-8
Maximum heap size(Mb)最大堆大小
