188 lines
5.4 KiB
Markdown
188 lines
5.4 KiB
Markdown
# Java文档注释规范倡议
|
||
|
||
## 什么是文档注释
|
||
|
||
> 以`/**`开头的就是文档注释，它只可出现在类头，方法头，类成员头上。这种注释会被maven打包后保留，且受JavaDoc与IDE识别。可以进行更为格式化的表现。
|
||
|
||
## 为什么要写好文档注释，文档注释有什么优势
|
||
|
||
### 1、文档注释受IDE识别，能提高编写代码的速度
|
||
|
||
我们使用IDEA编写代码时，调用到一个写了文档注释的方法。我们可以通过`Ctrl+Q`打开对应的文档注释。从而避免在调用方法时，需要打开该方法的代码页，导致两页代码翻来翻去导致思路打乱的情况。如图：
|
||
|
||
|
||
|
||
### 2、JavaDoc可以识别文档注释生成Java类文档
|
||
|
||
### 3、接口API文档框架JApiDocs可以识别
|
||
|
||
[JApiDocs](https://github.com/YeDaxia/JApiDocs)是一个基于文档注释生成API文档框架。它比起Swagger，可以避免单行内太多注解，或注解内容太长而导致代码臃肿难看的情况。
|
||
|
||
## 如何写好基本的文档注释
|
||
|
||
在写好方法声明后，在方法头输入“/**”后按回车，即可自动生成对应的文档模版，输入对应的内容即可。
|
||
正例：
|
||
|
||
|
||
反例：
|
||
|
||
反例不可被JavaDoc识别
|
||
|
||
|
||
## 文档注释基本格式以及常用注解详解
|
||
|
||
### 一、基本格式
|
||
|
||
```Java
|
||
/**
|
||
* 12315初查反馈延期
|
||
* @param targetUser 回填用户 {@link AICUser}
|
||
* @param caseguid 工单caseguid
|
||
* @param regId 工单号
|
||
* @param formType 表单类型
|
||
* @param prevDate 延期前日期 {@link java.util.Date}
|
||
* @param delayDate 延期日期（延期至该日期）{@link java.util.Date}
|
||
* @return 回填结果
|
||
* @author lroyia
|
||
* @since 2020年11月20日 14:07:48
|
||
*/
|
||
FeedbackResultDto acceptDelay(AICUser targetUser, String regId, String caseguid, String formType, Date prevDate, Date delayDate);
|
||
```
|
||
|
||
一般文档注释以下面的顺序进行编写
|
||
|
||
#### 1、方法描述
|
||
|
||
方法描述必须写在所有注解文档描述的前面，不然不会被识别
|
||
|
||
#### 2、参数说明
|
||
|
||
使用`@param`进行参数描述
|
||
使用格式：
|
||
|
||
```java
|
||
@param 参数名 参数描述
|
||
```
|
||
|
||
#### 3、返回说明
|
||
|
||
使用`@return` 进行返回内容标识
|
||
使用格式：
|
||
|
||
```java
|
||
@return 返回描述
|
||
```
|
||
|
||
#### 4、异常抛出说明
|
||
|
||
使用`@throws`或`@exception`进行异常说明
|
||
`@throws`与`@exception`注解均为异常注释注解，两者是同义词，作用一致
|
||
使用格式：
|
||
|
||
```java
|
||
@throws 方法抛出的异常类名 异常描述
|
||
@exception 方法抛出的异常类名 异常描述
|
||
```
|
||
|
||
#### 5、作者说明
|
||
|
||
使用`@author`进行作者标识
|
||
使用格式：
|
||
|
||
```java
|
||
@author 作者名称
|
||
```
|
||
|
||
#### 6、编写时间
|
||
|
||
使用`@since`进行编写时间标识，`@since`常用于标识方法从哪个版本开始编写，因为公司没有严格，细粒度的项目版本控制，所以暂时使用该注解进行时间描述
|
||
使用格式：
|
||
|
||
```java
|
||
@since 时间描述
|
||
```
|
||
|
||
### 二、常用注解详解
|
||
|
||
#### 1、@code
|
||
|
||
`@code`是用于文档中的代码格式化转义，相当于在文档中使用`<code>`标签
|
||
使用格式：
|
||
|
||
```java
|
||
{@code 修饰内容}
|
||
```
|
||
|
||
#### 2、@link
|
||
|
||
`@link`是用于进行档内文件超链接，常用语修饰一些方法对项目中相关的文件的连接。例如，方法使用了某个枚举，我们就可以在文档中使用`@link`生成对应枚举类的超链接，这样阅读者就可以直接点击文档中的超链接跳到对应的枚举类中。
|
||
使用格式：
|
||
|
||
```java
|
||
{@link 类名#方法名(参数名)}
|
||
```
|
||
|
||
#### 3、@see
|
||
|
||
`@see`是类文档引用注解，它与`@link`相似。但两者行为和注解位置不同。`@code`和`@link`均为*行内注解*均在`{}`花括号中使用，可在任何描述位置进行扩展修饰。`@see`是*行注解*，需要像`@param`一样占单行。`@link`默认行为是打开目标类指定位置，`@see`默认行为是展示目标的文档注释。
|
||
使用格式：
|
||
|
||
```java
|
||
@see 类名#方法名(参数名)
|
||
```
|
||
|
||
#### 4、@param
|
||
|
||
`@param`是专门对方法的参数进行描述的注解，被标识的参数信息会固定出现在文档的参数部位。
|
||
使用格式：
|
||
|
||
```java
|
||
@param 参数名 参数描述
|
||
```
|
||
|
||
#### 5、@return
|
||
|
||
`@return`是专门对方法的返回内容进行描述的注解，被标识的信息会固定出现在文档的返回部位。
|
||
使用格式：
|
||
|
||
```java
|
||
@return 返回描述
|
||
```
|
||
|
||
#### 6、@throws和@exception
|
||
|
||
`@throws`与`@exception`注解均为异常注释注解，两者是同义词，作用一致。在使用异常注释注解前，必须确保方法已使用throws关键字进行了相应的异常抛出声明。
|
||
使用格式：
|
||
|
||
```java
|
||
@throws 方法抛出的异常类名 异常描述
|
||
@exception 方法抛出的异常类名 异常描述
|
||
```
|
||
|
||
#### 7、@author
|
||
|
||
`@author`注解是专门用于标识方法作者的一个注解
|
||
使用格式：
|
||
|
||
```java
|
||
@author 作者名称
|
||
```
|
||
|
||
#### 8、@since
|
||
|
||
`@since`是专门用于标识方法/类的创建版本时间的一个注解。在没有明确的版本划分时，我们可以用来进行标识创建时间。
|
||
使用格式：
|
||
|
||
```java
|
||
@since 创建时间/版本描述
|
||
```
|
||
|
||
#### 9、@version
|
||
|
||
`@version`是专门用来标识当前方法/类的版本的注解，常在开发社区的开源项目中使用，一般公司不会进行。
|
||
使用格式：
|
||
|
||
```java
|
||
@version 版本号
|
||
```
|