IDEA定制文档注释

一 文档注释的必要性

• 对代码解释说明
• 方便自己复盘
• 方便与其他开发者合作
• 方便调用者操作使用
• 方便出问题时追责溯源
• 是软件开发中生成帮助文档说明书的必要部分

阅读参考代码注释的重要意义

二 常用文档注释分类

1. 作者文档注释
   用于标注开发者的个人信息,用于溯源责任人是必须的选项
   
2. 功能文档注释
   用于解释类或者方法的功能及参数等
   

三 常用文档注释

注释标签	解释
@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 [email protected]
 */

(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. 使用效果图

学习过程中, 有任何问题 , 都可以留言一起交流学习哦!!!