一、注释标签介绍
标记 | 说明 | 标签类型 |
---|---|---|
@author | 作者标识 | 包、类、接口 |
@version | 版本号 | 包、类、接口 |
@param | 方法的入参名及描述信息,如入参有特别要求,可在此注释 | 构造函数、方法 |
@return | 对函数返回值的注释 | 方法 |
@deprecated | 标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在.以此告之开发者不应再用这个API | 包、类、接口、值域、构造函数、方法 |
@throws | 构造函数或方法所会抛出的异常 | 构造函数、方法 |
@exception | 同@throws | 构造函数、方法 |
@see | 查看相关内容,如类,方法,变量等 | 包、类、接口、值域、构造函数、方法 |
@since | API在什么程序的什么版本后开发支持 | 包、类、接口、值域、构造函数、方法 |
@link | 链接到某个特定的成员对应的文档中 | 包、类、接口、值域、构造函数、方法 |
@link | 当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值 | 静态值域 |
二、IDEA生成JavaDoc文档
2.1、IDEA选择Tools
->Generate JavaDoc
2.2、注意以下三个地方
1.第一个是设置输入的地址
最好先弄一个空文件夹,再把地址定到那里,这个JavaDoc文件是一堆文件的,得放一个空文件夹好查看
2.第二个是设置语言
zh_CN
3.第三个是设置字符集编码
-encoding utf-8 -charset utf-8
4.查看效果
三、自定义注解模板
3.1、注解在类上
1.在创建类的时候,自动生成类注释.
打开Settings>Editor>File and Code Templates,Files页签下,选择Class/Interface/Enum,可以看到引用了#parse("File Header.java")
模版:
所以我们来修改模版即可,Includes页签下,选择File Header
模版,右侧即自定义模版,下面的Description中描述了支持的参数:
(1)@BelongsProject:当前项目的名称
(2)@BelongsPackage:当前包的名称
(3)@Author:作者姓名(可以写死,写成你的名字)
(4)@CreateTime:该类创建的时间
(5)@Description:对该类的描述(该类的功能)
(6)@Version:设置版本号,一般新创建的类都是1.0版本,这里写死就可以了。
保存之后,当你创建类的时候就会自动生成注释。
2.注释模板参考:
3.2、注解在方法上
1.新建模板:选中你刚才创建的组
-
修改Abbreviation 为 *;
-
修改Description,随便写点描述
-
修改模板内容,〈ENDEND〉可以使生成模板后,快速定位到description
* * $params$ * @return : $return$ * @author : Chiang * @description: 〈$END$〉 * @date : $DATE$ $TIME$ */
-
设置将模板应用于那些场景,一般选择EveryWhere-->Java即可,如果没有修改过,显示define,不然则显示为change
-
因为IDEA生成注释的默认方式是:/+模板名+快捷键(比如若设置模板名为,快捷键用Tab,则生成方式为:
/**+Tab
),把右侧的Expand with:改为Enter ,则生成方式为/**+Enter
。 -
选择右侧的Edit variables按钮,IDEA格式的模板只需要为每个参数选择对应的方法即可。 -
获取参数实现方式(params):
groovyScript("def result = '';def params = \"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {if(params[i] != '')result+='* @param: ' + params[i] + ((i < params.size() - 1) ? '\\r\\n ' : '')}; return result == '' ? null : '\\r\\n ' + result", methodParameters())
返回值实现方式(return):
groovyScript("def result=\"${_1}\"; if(result == \"void\"){return \"\";}else{return \"{@link \"+result+\"}\";}", methodReturnType())
-
设置成功后点击OK,返回项目新建一个方法,写完入参和返回值以后,在方法上面:
-
敲出:
/** + Enter
然后会显示: