关于 “文档注释”

0.1 关于 “文档注释”

0.2 作用

文档注释非常有用，比行注释、块注释有用得多。

1. 对于写了文旦注释的类、方法，任何使用到该类、方法的地方，把鼠标放在类名、方法名上，就会弹出来提示

   • 

2. 使用 JavaDoc 工具，可以从源码中抽取类、方法、成员等文档注释形成一个和源代码配套的 API 帮助文档，官方 API 文档也是这么生成的

   • 

0.3 编写文档注释

其实文档注释写起来跟行注释、块注释一样方便

在类、方法的上一行输入 /** 回车，就会自动生成带形参变量、返回值的模板：

然后补充文字说明就可以：

0.4 文档注释规范

格式：

1
2
3
4
5

/**
* 描述部分(description) 
* (空一行)
* 标记部分(block tags)
*/

常见的标记有：

1. @author 作者，没有特殊格式要求，名字或组织名称都可以

2. @version 软件版本号（注意不是java版本号），没有特殊格式要求

3. @param 方法参数，格式为： @param 参数名称 参数描述

   可以在参数描述中说明参数的类型 可以在参数名称和参数描述之间添加额外的空格来对齐 破折号或其他标点符号不能出现在参数描述之外的地方

4. @return 方法返回值，格式为： @return 返回值描述 ，如果方法没有返回值就不要写@return

5. @deprecated 应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API

6. @throws （或 @exception ）包含方法显式抛出的检查异常(Checked Exception)，至于非显示抛出的其他异常(Unchecked Exception)，除非特别有必要，否则就别写了。一个原则就是，只记录可控的问题，对于不可控的或不可预测的问题，不要往上面写。

完整的文档注释规范可以查看官方说明¹