diff --git a/solr部署说明文档.md b/应用部署/solr部署说明文档.md similarity index 100% rename from solr部署说明文档.md rename to 应用部署/solr部署说明文档.md diff --git a/Java文档注释规范倡议.md b/技术规范/Java文档注释规范倡议.md similarity index 96% rename from Java文档注释规范倡议.md rename to 技术规范/Java文档注释规范倡议.md index 8fcefc6..c05d43e 100644 --- a/Java文档注释规范倡议.md +++ b/技术规范/Java文档注释规范倡议.md @@ -1,187 +1,187 @@ -# Java文档注释规范倡议 - -## 什么是文档注释 - -> 以`/**`开头的就是文档注释，它只可出现在类头，方法头，类成员头上。这种注释会被maven打包后保留，且受JavaDoc与IDE识别。可以进行更为格式化的表现。 - -## 为什么要写好文档注释，文档注释有什么优势 - -### 1、文档注释受IDE识别，能提高编写代码的速度 - -我们使用IDEA编写代码时，调用到一个写了文档注释的方法。我们可以通过`Ctrl+Q`打开对应的文档注释。从而避免在调用方法时，需要打开该方法的代码页，导致两页代码翻来翻去导致思路打乱的情况。如图： - -![JavaDoc](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc1.jpg) - -### 2、JavaDoc可以识别文档注释生成Java类文档 - -### 3、接口API文档框架JApiDocs可以识别 - -[JApiDocs](https://github.com/YeDaxia/JApiDocs)是一个基于文档注释生成API文档框架。它比起Swagger，可以避免单行内太多注解，或注解内容太长而导致代码臃肿难看的情况。 - -## 如何写好基本的文档注释 - -在写好方法声明后，在方法头输入“/**”后按回车，即可自动生成对应的文档模版，输入对应的内容即可。 -正例： -![JavaDoc1](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc2.jpg) -![JavaDoc](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc1.jpg) -反例： -![JavaDoc3](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc3.jpg) -反例不可被JavaDoc识别 -![JavaDoc4](https://cloud.qiniu.lroyia.top/blog/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`是用于文档中的代码格式化转义，相当于在文档中使用``标签 -使用格式： - -```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 版本号 -``` +# Java文档注释规范倡议 + +## 什么是文档注释 + +> 以`/**`开头的就是文档注释，它只可出现在类头，方法头，类成员头上。这种注释会被maven打包后保留，且受JavaDoc与IDE识别。可以进行更为格式化的表现。 + +## 为什么要写好文档注释，文档注释有什么优势 + +### 1、文档注释受IDE识别，能提高编写代码的速度 + +我们使用IDEA编写代码时，调用到一个写了文档注释的方法。我们可以通过`Ctrl+Q`打开对应的文档注释。从而避免在调用方法时，需要打开该方法的代码页，导致两页代码翻来翻去导致思路打乱的情况。如图： + +![JavaDoc](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc1.jpg) + +### 2、JavaDoc可以识别文档注释生成Java类文档 + +### 3、接口API文档框架JApiDocs可以识别 + +[JApiDocs](https://github.com/YeDaxia/JApiDocs)是一个基于文档注释生成API文档框架。它比起Swagger，可以避免单行内太多注解，或注解内容太长而导致代码臃肿难看的情况。 + +## 如何写好基本的文档注释 + +在写好方法声明后，在方法头输入“/**”后按回车，即可自动生成对应的文档模版，输入对应的内容即可。 +正例： +![JavaDoc1](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc2.jpg) +![JavaDoc](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc1.jpg) +反例： +![JavaDoc3](https://cloud.qiniu.lroyia.top/blog/img/JavaDoc3.jpg) +反例不可被JavaDoc识别 +![JavaDoc4](https://cloud.qiniu.lroyia.top/blog/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`是用于文档中的代码格式化转义，相当于在文档中使用``标签 +使用格式： + +```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 版本号 +``` diff --git a/Markdown文档排版规范.md b/技术规范/Markdown文档排版规范.md similarity index 100% rename from Markdown文档排版规范.md rename to 技术规范/Markdown文档排版规范.md diff --git a/代码开发和版本发布管理规范.md b/技术规范/代码开发和版本发布管理规范.md similarity index 100% rename from 代码开发和版本发布管理规范.md rename to 技术规范/代码开发和版本发布管理规范.md diff --git a/数据库设计规范_v1.0.4.md b/技术规范/数据库设计规范_v1.0.4.md similarity index 100% rename from 数据库设计规范_v1.0.4.md rename to 技术规范/数据库设计规范_v1.0.4.md diff --git a/新兵作战指南（前端篇）.md b/技术规范/新兵作战指南（前端篇）.md similarity index 100% rename from 新兵作战指南（前端篇）.md rename to 技术规范/新兵作战指南（前端篇）.md diff --git a/checkstyle.xml b/配置参考/checkstyle.xml similarity index 100% rename from checkstyle.xml rename to 配置参考/checkstyle.xml diff --git a/maven-settings-demo.xml b/配置参考/maven-settings-demo.xml similarity index 100% rename from maven-settings-demo.xml rename to 配置参考/maven-settings-demo.xml