# Java文档注释规范倡议

## 什么是文档注释

> 以`/**`开头的就是文档注释，它只可出现在类头，方法头，类成员头上。这种注释会被maven打包后保留，且受JavaDoc与IDE识别。可以进行更为格式化的表现。

## 为什么要写好文档注释，文档注释有什么优势

### 1、文档注释受IDE识别，能提高编写代码的速度

我们使用IDEA编写代码时，调用到一个写了文档注释的方法。我们可以通过`Ctrl+Q`打开对应的文档注释。从而避免在调用方法时，需要打开该方法的代码页，导致两页代码翻来翻去导致思路打乱的情况。如图：

![JavaDoc](../img/JavaDoc1.jpg)

### 2、JavaDoc可以识别文档注释生成Java类文档

### 3、接口API文档框架JApiDocs可以识别

[JApiDocs](https://github.com/YeDaxia/JApiDocs)是一个基于文档注释生成API文档框架。它比起Swagger，可以避免单行内太多注解，或注解内容太长而导致代码臃肿难看的情况。

## 如何写好基本的文档注释

在写好方法声明后，在方法头输入“/**”后按回车，即可自动生成对应的文档模版，输入对应的内容即可。  
正例：
![JavaDoc1](../img/JavaDoc2.jpg)
![JavaDoc](../img/JavaDoc1.jpg)
反例：
![JavaDoc3](../img/JavaDoc3.jpg)
反例不可被JavaDoc识别
![JavaDoc4](../img/JavaDoc4.jpg)

## 文档注释基本格式以及常用注解详解

### 一、基本格式

```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 版本号
```