IDEA定制文档注释
一 文档注释的必要性
- 对代码解释说明
- 方便自己复盘
- 方便与其他开发者合作
- 方便调用者操作使用
- 方便出问题时追责溯源
- 是软件开发中生成帮助文档说明书的必要部分
阅读参考代码注释的重要意义
二 常用文档注释分类
- 作者文档注释
用于标注开发者的个人信息,用于溯源责任人是必须的选项
- 功能文档注释
用于解释类或者方法的功能及参数等
三 常用文档注释
注释标签 | 解释 |
---|---|
@author | 作者(只出现在类和接口的文档中) |
@version | 数字指的是版本号 |
@since | 数字指的jdk版本 |
@param | 指的是方法的参数,后面跟上 参数名 + 空格 + 参数说明 |
@return | 对返回值的说明 |
@throws | 抛出异常说明, 后面跟上 异常名 + 空格 + 异常跑出原因 |
详细标签[了解即可
]
标签 | 描述 | 语法 |
---|---|---|
@author | 添加类的作者 | @author name-text |
{@code} | 不把文本转换成 HTML 标记和嵌套的 Java 标签而用代码字体展示它 | {@code text} |
{@docRoot} | 表示从任何生成页面到生成文档的根目录的相对路径 | {@docRoot} |
@deprecated | 添加一个注释暗示 API 应该不再被使用 | @deprecated deprecated-text |
@exception | 用类名和描述文本给生成的文档添加一个副标题 | @exception class-name description |
{@inheritDoc} | 从最近的可继承的类或可实现的接口继承注释 | Inherits a comment from the immediate surperclass. |
{@link} | 用指向特定的包,类或者一个引用类的成员名的文档的可见文本标签插入在线链接 | {@link package.class#member label} |
{@linkplain} | 和{@link}相同,除了链接的标签用纯文本标示而不是代码字体 | {@linkplain package.class#member label} |
@param | 给“参数”区域添加一个有特定参数名且后跟着特定描述的参数 | @param parameter-name description |
@return | 添加一个有描述文本的“Returns”区域 | @return description |
@see | 添加带有链接或者指向引用的文本入口的标题 | “See Also” |
@serial | 在默认的序列化字段的文本注释中使用 | @serial field-description include exclude |
@serialData | 记录由 writeObject( ) 或 writeExternal( )方法所写的数据 | @serialData data-description |
@serialField | 记录一个 ObjectStreamField 成分 | @serialField field-name field-type field-description |
@since | 给生成的文档添加一个带有特定 since 文本的”Since”标题 | @since release |
@throws | @throw 和 @exception 标签是同义词 | @throws class-name description |
{@value} | 当{@value}被用在一个静态字段的文本注释中,它展示了那个常量的值 | {@value package.class#field} |
@version | 当 -version 选项被使用时用特定的 version w文本给生成的文本添加一个“Version”副标题 | @version version-text |
四 Java开发中常用文档注释的快速设置
(1) 创建Java类时自动生成注释
/**
* @author:Steven
* @date: ${DATE}
* @time: ${TIME}
* @function:
* @since:
* @version:
* @email steven.start@aliyun.com
*/
(2) 手动生成文档注释
1. 手动作者文档注释
**
* @email steven.start@aliyun.com
* @author:Steven
* @date: $date$
* @time: $time$
*/
使用方法,快捷键可以自定义
2. 手动文档功能设置
** @function 功能描述 $end$
* @author:Steven
* @param: $param$
* @return: $return$
* @time: $date$-$time$
*/
使用方法
3. 使用效果图
学习过程中, 有任何问题 , 都可以留言一起交流学习哦!!!