[Add] documents

yihleego · Aug 19, 2020 · 08803a3 · 08803a3
1 parent 8be70df
commit 08803a3
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 64 deletions.
diff --git a/README.ZH_CN.md b/README.ZH_CN.md
@@ -1,11 +1,11 @@
 # MyPages
 
-[English Document 英文版](README.md)
-
 MyPages是Java实现基于[MyBatis](https://github.com/mybatis/mybatis-3)的开源分页插件，最大程度简化数据库分页查询操作，支持市面上大部分数据库，如：MySQL、PostgreSQL、Oracle、SQLServer等。
 
 ## 安装
 
+请确保您的Java版本在1.8及以上。
+
 ```bash
 $ git clone https://github.com/yihleego/mypages.git
 $ cd mypages
@@ -17,14 +17,10 @@ $ mvn clean install
 ### Maven
 
 ```xml
-<properties>
-    <mypages.version>1.0.0</mypages.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages</artifactId>
-    <version>${mypages.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -46,10 +42,12 @@ implementation 'io.leego:mypages:1.0.0'
 
 ## 文档
 
-> * [User Guide (English)](docs/USERGUIDE.md)
+[English Document 英文版](README.md)
+
 > * [用户指南 (中文版)](docs/USERGUIDE.ZH_CN.md)
-> * [MyPages-Spring-Boot-Starter (English)](docs/STARTER_USERGUIDE.md)
-> * [MyPages-Spring-Boot-Starter (中文版)](docs/STARTER_USERGUIDE.ZH_CN.md)
+> * [User Guide (English)](docs/USERGUIDE.md)
+> * [mypages-spring-boot-starter (中文版)](docs/STARTER_USERGUIDE.ZH_CN.md)
+> * [mypages-spring-boot-starter (English)](docs/STARTER_USERGUIDE.md)
 
 ## 交流
 

diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
 # MyPages
 
-[Chinese Document 中文版](README.ZH_CN.md)
-
 MyPages is a java based, open source pagination plugin for [MyBatis](https://github.com/mybatis/mybatis-3) that simplifies database paging queries.
 Many databases, one plugin.
 
 ## Installation
 
+Please make sure the Java version is 1.8 and above.
+
 ```bash
 $ git clone https://github.com/yihleego/mypages.git
 $ cd mypages
@@ -18,14 +18,10 @@ $ mvn clean install
 ### Maven
 
 ```xml
-<properties>
-    <mypages.version>1.0.0</mypages.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages</artifactId>
-    <version>${mypages.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -47,10 +43,12 @@ implementation 'io.leego:mypages:1.0.0'
 
 ## Documentation
 
+[Chinese Document 中文版](README.ZH_CN.md)
+
 > * [User Guide (English)](docs/USERGUIDE.md)
 > * [用户指南 (中文版)](docs/USERGUIDE.ZH_CN.md)
-> * [MyPages-Spring-Boot-Starter (English)](docs/STARTER_USERGUIDE.md)
-> * [MyPages-Spring-Boot-Starter (中文版)](docs/STARTER_USERGUIDE.ZH_CN.md)
+> * [mypages-spring-boot-starter (English)](docs/STARTER_USERGUIDE.md)
+> * [mypages-spring-boot-starter (中文版)](docs/STARTER_USERGUIDE.ZH_CN.md)
 
 ## Contact
 

diff --git a/docs/STARTER_USERGUIDE.ZH_CN.md b/docs/STARTER_USERGUIDE.ZH_CN.md
@@ -11,14 +11,10 @@ MyPages是Java实现基于[MyBatis](https://github.com/mybatis/mybatis-3)的开
 ## 3.1 Maven
 
 ```xml
-<properties>
-    <mypages-spring-boot-starter.version>1.0.0</mypages-spring-boot-starter.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages-spring-boot-starter</artifactId>
-    <version>${mypages-spring-boot-starter.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -30,6 +26,27 @@ implementation 'io.leego:mypages-spring-boot-starter:1.0.0'
 
 # 4. 配置
 
+|Property|Description|
+|:-|:-|
+|spring.mypages.enabled|是否启用mypages。|
+|spring.mypages.sql-dialect|指定sql dialect，如：`MySQL`、`PostgreSQL`、`Oracle`等。|
+|spring.mypages.count-expr|设置count字段名称，默认值为`*`。|
+|spring.mypages.page-field|从参数字段中获取`page`值。|
+|spring.mypages.size-field|从参数字段中获取`size`值。|
+|spring.mypages.offset-field|从参数字段中获取`offset`值。|
+|spring.mypages.rows-field|从参数字段中获取`rows`值。|
+|spring.mypages.count-expr-field|从参数字段中获取count表达式。|
+|spring.mypages.count-method-name-field|从参数字段中获取自定义count方法名称。|
+|spring.mypages.enable-count-field|从参数字段中判断是否启用count。|
+|spring.mypages.skip-query-if-count-equals-zero|是否跳过查询如果结果数量为`0`。|
+|spring.mypages.use-generated-if-count-method-is-missing|是否使用自动生成的count方法如果指定count方法不存在。|
+|spring.mypages.default-page|如果`page`为空或小于`1`，则用`default-page`替换`page`。|
+|spring.mypages.default-size|如果`size`为空或小于`1`，则用`default-size`替换`size`。|
+|spring.mypages.max-page|如果`page`大于`max-page`，则用`max-page`替换`page`。|
+|spring.mypages.max-size|如果`size`大于`max-size`，则用`max-size`替换`size`。|
+
+## 示例
+
 使用分页参数定义一个类，并配置参数字段名。
 
 ```java
@@ -45,9 +62,9 @@ public class Pageable {
 }
 ```
 
-请注意sql-dialect必须被配置。
+**请注意sql-dialect必须被配置。**
 
-## 4.1 Properties
+Properties
 
 ```properties
 spring.mypages.enabled=true
@@ -68,7 +85,7 @@ spring.mypages.max-page=10000
 spring.mypages.max-size=10000
 ```
 
-## 4.2 Yaml
+Yaml
 
 ```yaml
 spring:

diff --git a/docs/STARTER_USERGUIDE.md b/docs/STARTER_USERGUIDE.md
@@ -11,14 +11,10 @@ Please make sure the Java version is 1.8 and above.
 ## 3.1 Maven
 
 ```xml
-<properties>
-    <mypages-spring-boot-starter.version>1.0.0</mypages-spring-boot-starter.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages-spring-boot-starter</artifactId>
-    <version>${mypages-spring-boot-starter.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -30,6 +26,27 @@ implementation 'io.leego:mypages-spring-boot-starter:1.0.0'
 
 # 4. Configuration
 
+|Property|Description|
+|:-|:-|
+|spring.mypages.enabled|Whether to enable mypages.|
+|spring.mypages.sql-dialect|The sql dialect such as `MySQL`, `PostgreSQL`, `Oracle`, etc.|
+|spring.mypages.count-expr|The column name or expression, the default value is `*`.|
+|spring.mypages.page-field|The `page` field name of the parameter.|
+|spring.mypages.size-field|The `size` field name of the parameter.|
+|spring.mypages.offset-field|The `offset` field name of the parameter.|
+|spring.mypages.rows-field|The `rows` field name of the parameter.|
+|spring.mypages.count-expr-field|The count expression field name of the parameter.|
+|spring.mypages.count-method-name-field|The `count-method-name` field name of the parameter.|
+|spring.mypages.enable-count-field|The `enable-count` field name of the parameter.|
+|spring.mypages.skip-query-if-count-equals-zero|Whether to skip query if total value equals zero.|
+|spring.mypages.use-generated-if-count-method-is-missing|Whether to use generated if the specified count method is missing.|
+|spring.mypages.default-page|Replaces the `page` with `default-page` if the `page` is `null` or less than `1`.|
+|spring.mypages.default-size|Replaces the `size` with `default-size` if the `size` is `null` or less than `1`.|
+|spring.mypages.max-page|Replaces the `page` with `max-page` if the `page` is greater than `max-page`.|
+|spring.mypages.max-size|Replaces the `size` with `max-size` if the `size` is greater than `max-size`.|
+
+## For example
+
 Define a class with paging parameters.
 
 ```java
@@ -45,9 +62,9 @@ public class Pageable {
 }
 ```
 
-Please notice that the sql-dialect is required.
+**Please notice that the sql-dialect is required.**
 
-## 4.1 Properties
+Properties
 
 ```properties
 spring.mypages.enabled=true
@@ -68,7 +85,7 @@ spring.mypages.max-page=10000
 spring.mypages.max-size=10000
 ```
 
-## 4.2 Yaml
+Yaml
 
 ```yaml
 spring:

diff --git a/docs/USERGUIDE.ZH_CN.md b/docs/USERGUIDE.ZH_CN.md
@@ -11,14 +11,10 @@ MyPages是Java实现基于[MyBatis](https://github.com/mybatis/mybatis-3)的开
 ## 3.1 Maven
 
 ```xml
-<properties>
-    <mypages.version>1.0.0</mypages.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages</artifactId>
-    <version>${mypages.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -144,7 +140,7 @@ public class QueryTests {
 
 ## 6.1 注解 (推荐)
 
-使用 ```@Pagination```, ```@Page```, ```@Size```, ```@Offset```, ```@Rows``` 注解.
+使用 `@Pagination`、`@Page`、`@Size`、`@Offset`、`@Rows` 注解.
 
 ```java
 @Pagination
@@ -161,7 +157,7 @@ public class Pageable {
 }
 ```
 
-更多注解: ```@CountExpr```, ```@CountMethodName```, ```@DisableCount```, ```@DisablePagination```.
+更多注解: `@CountExpr`、`@CountMethodName`、`@DisableCount`、`@DisablePagination`.
 
 ## 6.2 PaginationInterceptor配置 (推荐)
 
@@ -218,7 +214,7 @@ public class QueryTests {
 }
 ```
 
-### 6.2.2 MyBatis ```@Param```
+### 6.2.2 MyBatis `@Param`
 
 假设存在如下定义的Mapper：
 
@@ -287,9 +283,9 @@ PaginationSettings settings = PaginationSettings.builder()
     .rowsField("rows") // 从参数字段中获取rows值。
     .countExprField("countExpr") // 从参数字段中获取count表达式。
     .countMethodNameField("countMethodName") // 从参数字段中获取自定义count方法名称。
-    .enableCountField("enableCount") // 是否启用count。
-    .skipQueryIfCountEqualsZero(true) // 是否跳过count如果总数量为0。
-    .useGeneratedIfCountMethodIsMissing(true) // 是否生成的查询方法如果指定查询方法不存在。
+    .enableCountField("enableCount") // 从参数字段中判断是否启用count。
+    .skipQueryIfCountEqualsZero(true) // 是否跳过查询如果总数量为0。
+    .useGeneratedIfCountMethodIsMissing(true) // 是否使用自动生成的count方法如果指定count方法不存在。
     .defaultPage(1) // 如果page为空或小于1，则用default-page替换page。
     .defaultSize(10) // 如果size为空或小于1，则用default-size替换size。
     .maxPage(10000) // 如果page大于max-page，则用max-page替换page。
@@ -298,9 +294,9 @@ PaginationSettings settings = PaginationSettings.builder()
 PaginationInterceptor interceptor = new PaginationInterceptor(settings);
 ```
 
-## 6.3 继承 ```io.leego.mypages.util.Pageable```
+## 6.3 继承 `io.leego.mypages.util.Pageable`
 
-定义一个继承 ```io.leego.mypages.util.Pageable```的类.
+定义一个继承 `io.leego.mypages.util.Pageable`的类.
 
 ```java
 public class PageableDTO extends io.leego.mypages.util.Pageable {
@@ -420,9 +416,9 @@ PaginationInterceptor interceptor = new PaginationInterceptor(settings);
 
 # 9. 查询结果
 
-如果调用执行成功结束，它将返回一个```PaginationCollection```实例。
+如果调用执行成功结束，它将返回一个`PaginationCollection`实例。
 
-## 9.1 使用 ```io.leego.mypages.util.Page``` 
+## 9.1 使用 `io.leego.mypages.util.Page` 
 
 #### 9.1.1 包装
 

diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
@@ -11,14 +11,10 @@ Please make sure the Java version is 1.8 and above.
 ## 3.1 Maven
 
 ```xml
-<properties>
-    <mypages.version>1.0.0</mypages.version>
-</properties>
-
 <dependency>
     <groupId>io.leego</groupId>
     <artifactId>mypages</artifactId>
-    <version>${mypages.version}</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
@@ -144,7 +140,7 @@ public class QueryTests {
 
 ## 6.1 Annotations (Recommended)
 
-Using ```@Pagination```, ```@Page```, ```@Size```, ```@Offset```, ```@Rows``` annotations.
+Using `@Pagination`, `@Page`, `@Size`, `@Offset`, `@Rows` annotations.
 
 ```java
 @Pagination
@@ -161,7 +157,7 @@ public class Pageable {
 }
 ```
 
-More annotations: ```@CountExpr```, ```@CountMethodName```, ```@DisableCount```, ```@DisablePagination```.
+More annotations: `@CountExpr`, `@CountMethodName`, `@DisableCount`, `@DisablePagination`.
 
 ## 6.2 PaginationInterceptor Configuration (Recommended)
 
@@ -218,7 +214,7 @@ public class QueryTests {
 }
 ```
 
-### 6.2.2 MyBatis ```@Param```
+### 6.2.2 MyBatis `@Param`
 
 Assume there is a mapper interface defined like the following:
 
@@ -286,8 +282,8 @@ PaginationSettings settings = PaginationSettings.builder()
     .offsetField("offset") // Obtains the offset value from parameter.
     .rowsField("rows") // Obtains the rows value from parameter.
     .countExprField("countExpr") // Obtains the count expression from parameter.
-    .countMethodNameField("countMethodName") // Obtains the count method name from parameter.
-    .enableCountField("enableCount") // Whether to enable count.
+    .countMethodNameField("countMethodName") // Obtains the count-method-name from parameter.
+    .enableCountField("enableCount") // Obtains the enable-count from parameter.
     .skipQueryIfCountEqualsZero(true) // Whether to skip query if total quantity equals zero.
     .useGeneratedIfCountMethodIsMissing(true) // Whether to use generated if the specified count method is missing.
     .defaultPage(1) // Replaces the page with default-page if the page is null or less than 1.
@@ -298,9 +294,9 @@ PaginationSettings settings = PaginationSettings.builder()
 PaginationInterceptor interceptor = new PaginationInterceptor(settings);
 ```
 
-## 6.3 Extends ```io.leego.mypages.util.Pageable```
+## 6.3 Extends `io.leego.mypages.util.Pageable`
 
-Define a class extends ```io.leego.mypages.util.Pageable```.
+Define a class extends `io.leego.mypages.util.Pageable`.
 
 ```java
 public class PageableDTO extends io.leego.mypages.util.Pageable {
@@ -420,9 +416,9 @@ PaginationInterceptor interceptor = new PaginationInterceptor(settings);
 
 # 9. Query Results
 
-If the invocation proceed, it will return an instance of the ```PaginationCollection```.
+If the invocation proceed, it will return an instance of the `PaginationCollection`.
 
-## 9.1 Using ```io.leego.mypages.util.Page``` 
+## 9.1 Using `io.leego.mypages.util.Page` 
 
 #### 9.1.1 Wrap