JAVA注释详解及个性化生成javadoc文档
JAVA注释详解及个性化生成javadoc文档
一、注释详解
注释主要就是对程序的解释说明
- 单行注释（// 注释文字）
- 多行注释（/* 注释文字 */）
- 文档注释（/** 注释文档 */）JAVA特有
文档注释通过 Javadoc 生成相应的 API 帮助文档，主要用来说明类、成员变量和方法的功能。
文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc 只处理这些地方的文档注释，而忽略其它地方的文档注释。
Javadoc 是 Sun 公司提供的一种工具，它可以从程序源代码中抽取类、方法、成员等注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时以一套特定的标签注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档。
其实主要讲的还是文档注释，我们先用一段代码来演示，可以看到，代码中开头的使用了文档注释，内容包含了作者、时间和详情，接着采用了多行注释解释了单行多行的作用。方法内部也写了一些内容，我们复制内容到记事本并将文件名改为DocNote.java
/**这是我们第一次学习javadoc
* @author ChenJiaYi
* @version jdk11.0
*/
/*
单行注释和多行注释的作用：
①对缩写的程序进行解释说明，增强可读性
②调试所写的代码
*/
public class DocNote {
/*
如下的main方法是程序的入口，
main的格式是固定的
*/
/**如下的方式是main()，作用：程序的入口
* @param args 输出HelloWorld
*/
public static void main(String[] args) {
//单行注释：如下语句表示输入到控制台
System.out.println("HelloWorld");
}
}
我们将这个文件放在了D:\java目录下，到文件夹目录下按住shift+鼠标右键，打开Powershell窗口，或cmd进入当前文件夹
输入以下代码，简单了解一下意思：输出文件的目标目录名为myDoc，包含作者，版本号字段，编码是UTF-8
javadoc -d myDoc -author -version -encoding UTF-8 DocNote.java
便在当前文件夹生成了相应文档
我们打开index.html查看内容
首先可以看见我们定义在头部的文档注释，这是我们第一次学习javadoc
以及方法说明和参数信息
在上面，我们使用了@author 作者 、@version 版本 、 @param 参数 那么Javadoc还可以识别哪些标签我在下表中列出来
| 标签 | 描述 | 示例 |
|---|---|---|
| @author | 作者标识 | @author ChenJiaYi |
| @deprecated | 指名一个过期的类或成员，表明该类或方法不建议使用 | @deprecated description |
| {@docRoot} | 指明当前文档根目录的路径 | Directory Path |
| @exception | 可能抛出异常的说明，一般用于方法注释 | @exception exception-name explanation |
| {@inheritDoc} | 从直接父类继承的注释 | Inherits a comment from the immediate surperclass. |
| {@link} | 插入一个到另一个主题的链接 | {@link name text} |
| {@linkplain} | 插入一个到另一个主题的链接，但是该链接显示纯文本字体 | Inserts an in-line link to another topic. |
| @param | 说明一个方法的参数 | @param parameter-name explanation |
| @return | 说明返回值类型，一般用于方法注释，不能出现再构造方法中 | @return explanation |
| @see | 指定一个到另一个主题的链接 | @see anchor |
| @serial | 说明一个序列化属性 | @serial description |
| @serialData | 说明通过 writeObject() 和 writeExternal() 方法写的数据 | @serialData description |
| @serialField | 说明一个 ObjectStreamField 组件 | @serialField name type description |
| @since | 说明从哪个版本起开始有了这个函数 | @since release |
| @throws | 和 @exception 标签一样. | The @throws tag has the same meaning as the @exception tag. |
| {@value} | 显示常量的值，该常量必须是 static 属性。 | Displays the value of a constant, which must be a static field. |
| @version | 指定类的版本，一般用于类注释 | @version info |
在 cmd（命令提示符）中输入javadoc -help就可以看到 Javadoc 的用法和选项（前提是安装配置了JDK），下面列举 Javadoc 命令的常用选项：
| 名称 | 说明 |
|---|---|
| -public | 仅显示 public 类和成员 |
| -protected | 显示 protected/public 类和成员（默认值） |
| -package | 显示 package/protected/public 类和成员 |
| -private | 显示所有类和成员 |
| -d | 输出文件的目标目录 |
| -version | 包含 @version 段 |
| -author | 包含 @author 段 |
| -splitindex | 将索引分为每个字母对应一个文件 |
| -windowtitle | 文档的浏览器窗口标题 |
二、IDEA自定义自动生成java文件开头注释
简单了解了一下Javadoc通过DOS命令生成帮助文档后，我们讲解一下idea怎么使用自定义头部注释以及进一步的使用。
首先，学会了java文档注释后，一般我们会在头部注释上我们的称谓和版本号，如果每次开发都需要这一步骤，久而久之便会觉得繁琐，下面我们就通过idea自动为我们创建的每个java文件头部生成注释。
打开设置面板，然后填写注释模板：
File => setting => editor => File and Code Templates
按照图片步骤一步一步走即可设置完成
三、自定义javadoc标签
我们使用文档注释的时候总会想使用一些其他的标签来进行使用，但是如果使用了自定义的标签，没做配置的话就会出现错误：未知标记xxx
例如我们想要一个文档创建时间@CreateDate，如果直接写在头部的话就会出现上述错误
那我们想要自定义标签的话要如何使用呢，通过javadoc -help我们可以知道我们可以通过 -tag指令定制标记
通过查看官方文档，我们可以知道其中参数的意义
其中，name属性就是你想要自定义标记的名称，header便是在javadoc中显示的标题。
locations我个人使用习惯是都选择a，当然你可以根据文档需求来针对性使用。
例如：自定义一个创建时间标签，对应的tag命令便是： -tag CreateDate:a:"创建时间:"
/**
* @author ChenJiaYi
* @version jdk11.0
* @CreateDate 2020/10/03
*/
相应的整行dos指令应为
javadoc -d myDoc -author -version -encoding UTF-8 -tag CreateDate:a:"创建时间:" DocNote.java
四、使用IDEA生成我们想要的代码文档注释（最终版）
1、定义头部文档注释
重复二操作
一般头部只需要简单定义一下作者，创建时间和详情，可自行添加其他
/**
*@author ChenJiaYi
*@CreateDate ${DATE}
*@ProjectDetails [项目简述]
*/
2、java类中的方法快捷键生成文档注释
首先要新建一个Group ，通过以下步骤 ：File => Setting=> Editor=> Live Templates 点击右边上面那个绿色的+号，选择Template Group双击，然后弹出一个窗口，起名，然后点击ok，我这里起名为chenjiayiGroup
完成后就成功新建了一个chenjiayiGroup模板组，之后选中模板组点击+号，点击Live Template之后，将会新建一个模板，并且光标定位到了需要你输入快捷键的方框中，之后键入所需要的信息。我这里快捷键设置为cjy，描述为在方法内容敲入cjy时，在该方法内添加文档注释
/**
*描述:
*@param $param$
*@return $return$
*@author ChenJiaYi
*@CreateDate $date$ $time$
*@update [序号][日期YYYY-MM-DD][更改人姓名][变更描述]
*/
点击Edit Template选中相应方法，点击ok完成
最后，点击Define，选择java即可，或者根据自己的需求选择，点击ok
3、测试及配置
完成上诉内容后，我们重新创建一个java文件进行测试，可以发现新建的java文件以及自动生成了我们想要的文档注释
简单编写一段代码进行测试
/**
* @author ChenJiaYi
* @CreateDate 2020/10/3
* @ProjectDetails [项目简述]
*/
public class DocTest {
public static String sayHello(String username){
return "hello"+username;
}
}
输入cjy后可以发现出现快捷方式，就是我们刚刚设置的，点击回车
即可生成我们想要的方法文档注释，这个方法有点bug就是需要在方法内部才能自动生成对应参数，我们需要自己把注释剪切到方法外部去，不过如果对文档注释要求比较多的项目，这样肯定是更加方便的，快捷键也可以在方法外部敲，但是参数和返回值就需要自己去敲击，没有办法自动生成，所以直接再外部敲也可以，看个人需求
将内容移动至方法外并进行微调说明
可以看到，在头部文档注释及方法文档注释中我们使用了自定义的javadoc标签，如果没有配置那么生成javadoc文档便会报错，报错信息上面有讲，那我们要怎么在idea进行配置呢，在idea标签栏中点击Tools，可以看到Generate JavaDoc，点击进去
出现此界面，根据图片进行设置
Locale：zh-CN
Other command line arquments: -tag ProjectDetails:a:"项目详情:" -tag update:a:"项目更改:" -tag CreateDate:a:"创建时间:" -encoding UTF-8 -charset UTF-8
点击ok生成javadoc文档
可以看见文档注释生成的api文档与我们所写一致，测试结束
java注释学习及idea相关设置图文教程到这里就结束了，如果这篇文章对你有帮助的话，关注点赞留言就是对博主最大的支持！后续我还会持续更博，喜欢我的创作风格的不要忘记关注我！