-
Java文档注释（拓展）
Java文档注释（拓展）
学而不思则罔，思而不学则殆。 ——《论语·为政》
Java的三种注释：
* 单行注释
* 多行注释
* 文档注释
Java文档注释：
使用 /* */ 将文档注释内容括起来。
文档注释概览
文档注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。
相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。
例如：
类注释。
类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。这个规则也适用于接口注释。
方法注释。
方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。
文档注释内容
由描述部分和标记部分组成。
描述部分就是功能介绍、方法解释等的内容；
标记部分前有标记标签，例如@author、@version......
描述部分
描述部分的第一行应该是一句对类、接口、方法等的简单描述，这句话最后会被 javadoc 工具提取并放在索引目录中。
跟在第一个英文句号之后的tab、空行或行终结符规定了第一句的结尾。
除了普通的文本之外，描述部分可以使用：
-
HTML语法标签，例如 xxx
-
javadoc规定的特殊标签，例如 {@link xxx} 。
标签的语法规则是：{@标签名 标签内容}
需要注意的地方：
-
标签在有javadoc工具生成文档时会转化成特殊的内容，比如 {@link URL} 标签会被转化成指向URL类的超链接
-
如果注释包含多段内容，段与段之间需要用 <p> 分隔，空行是没用的
-
为了避免一行过长影响阅读效果，务必将每行的长度限制在80个字符以内
-
善用javadoc工具的复制机制避免不必要的注释：
如果一个方法覆盖了父类的方法或实现了接口种的方法，那么javadoc工具会在该注释里添加指向原始方法的链接，此外如果新方法没有注释，那么javadoc会把原始方法的注释复制一份作为其注释，但是如果新方法有注释了，就不会复制了。
标记部分
标记部分跟在描述部分之后，且前面必须有一个空行间隔
所有标签：
| 标签 | 描述 |
|---|---|
| @author | 标识一个类的作者 |
| @deprecated | 指名一个过期的类或成员 |
| {@docRoot} | 指明当前文档根目录的路径 |
| @exception | 标志一个类抛出的异常 |
| {@inheritDoc} | 从直接父类继承的注释 |
| {@link} | 插入一个到另一个主题的链接 |
| {@linkplain} | 插入一个到另一个主题的链接，但是该链接显示纯文本字体 |
| @param | 说明一个方法的参数 |
| @return | 说明返回值类型 |
| @see | 指定一个到另一个主题的链接 |
| @serial | 说明一个序列化属性 |
| @serialData | 说明通过writeObject( ) 和 writeExternal( )方法写的数据 |
| @serialField | 说明一个ObjectStreamField组件 |
| @since | 标记当引入一个特定的变化时 |
| @throws | 和 @exception标签一样. |
| {@value} | 显示常量的值，该常量必须是static属性。 |
| @version | 指定类的版本（不是Java版本） |
常见标签:
- @author 作者，没有特殊格式要求，名字或组织名称都可以
- @version 软件版本号（注意不是java版本号），没有特殊格式要求
- @param 方法参数，格式为： @param 参数名称 参数描述
-
可以在参数描述中说明参数的类型
-
可以在参数名称和参数描述之间添加额外的空格来对齐
-
破折号或其他标点符号不能出现在参数描述之外的地方
-
@return 方法返回值，格式为： @return 返回值描述 ，如果方法没有返回值就不要写@return
-
@deprecated 应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API，比如：
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
- @throws （或 @exception ）包含方法显式抛出的检查异常(Checked Exception)，至于非显示抛出的其他异常(Unchecked Exception)，除非特别有必要，否则就别写了。一个原则就是，只记录可控的问题，对于不可控的或不可预测的问题，不要往上面写。
检查异常：在try语法块中触发，在catch块中捕获的异常，这些异常会由编译器在编译阶段检查并强制程序员处理
非检查异常：包括运行时异常(RuntimeException)和错误(Error)。
- 自定义标记
注释风格：
- 按照如下顺序提供标记
@author（只出现在类和接口的文档中）
@version（只出现在类和接口的文档中）
@param（只出现在方法或构造器的文档中）
@return（只出现在方法中）
@exception（从java1.2之后也可以使用@thrown替代）
@see
@since
@serial（也可以使用@serialField或@serialData替代）
@deprecated
此外，如果有多个相同标记，也要注意顺序：
多个@author标记，应该按照时间顺序排列，即原作者应该排在第一个位置
多个@param标记，应该按照参数定义的顺序排列
多个@exception（或是@thrown）应该按照异常的字母顺序排列
多个@see标记，应该按照注释的逻辑顺序排列，即从最近的到最远的，从最具体的到最一般的
- 必须包含的标记
如果方法有参数，@param标记必须包含，而且每个对应一个参数
如果方法有返回值，@return标记必须包含
其他注释
-
包级别的文档注释
从java1.2起允许包级别的文档注释，用以描述包信息。每个包都可以有自己的包文档注释，这些注释被写在叫package.html的单独文件中，并且放至于与源码(*.java)相同的路径下，注意，一定不能单独放置在其他路径。
javadoc工具按照以下流程处理package.html:
把主要内容复制到最终生成的package-summary.html文件中
处理@see, @since, 或{@link}标记
把第一句话复制到javadoc的索引中
在包注释主要介绍一下这个包大致是做什么用的、背景信息、在使用方面需要注意的地方等等信息
-
匿名、内部类的文档注释
javadoc不会提取内部类的文档注释，所以如果想要在最终生成的文档中包含内部类的信息，方法就是——写在外部类的文档注释里。
文档注释生成文档时中文乱码问题
编写文档注释：
命令行窗口输入javadoc命令生成文档，发现出现以下报错：
原因：
是因为命令行窗口当前的编码为GBK，而文档注释里存在中文，GBK编码不支持中文，从而导致乱码。（右键窗口白色部分点击属性查看命令行窗口编码）
解决方法：只需要在 javadoc 命令后加入参数 -encoding utf-8 -charset utf-8
解释一下上述参数的意思：
-d：生成一个文件夹接受生成的文档文件，后面的 HelloDoc 为文件夹名。
-author、-version：为显示文档的作者和版本，对应文档注释里的@author、@version。
-encoding utf-8 -charset utf-8：则是将该文档注释的编码解码形式修改为utf-8，从而解决中文乱码问题。
通过上述操作，就能看到在Java文件目录下生成一个HelloDoc文件夹。
点击index.html文件就可以看到我们的注释文档。
后记
本文章文档注释内容部分取自文章（https://www.cnblogs.com/boring09/p/4274893.html ），有删减。
能力有限，难免有遗漏或错误，如有发现望指正。
出处：https://www.cnblogs.com/xiaozhao01/p/15916043.html
