doc: introduce CollectionTool class

docs/en-us/doc/collection-tools.md

@@ -0,0 +1,131 @@
+Collection Tools
+---
+
+During test data preparation, various collection types are often used. However, collection data initialization in Java needs series of redundant call to the `add()` or `put()` method, making the code very tedious.
+
+Inspired by the collection operations of Kotlin language, `TestableMock` draws on a set of concise collection construction method, which makes the creation of Java collection objects elegant.
+
+The utility class `CollectionTool` provides following global static methods:
+
+## arrayOf
+
+Quickly construct an array of any type, equivalent to Kotlin's `arrayOf()` method.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.arrayOf;
+
+// Construct a string array
+String[] manyWords = arrayOf("this", "is", "an", "example");
+
+// Construct a double array
+Double[] manyValues = arrayOf(1.0D, 2.0D, 3.0D);
+```
+
+## listOf
+
+Quickly construct an list of any type, equivalent to Kotlin's `mutableListOf()` method.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.listOf;
+
+// Construct a string list
+List<String> manyWords = listOf("this", "is", "an", "example");
+
+// Construct a double list        
+List<Double> manyValues = listOf(1.0D, 2.0D, 3.0D);
+```
+
+## setOf
+
+Quickly construct an set of any type, equivalent to Kotlin's `mutableSetOf()` method.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.setOf;
+
+// Construct a string set
+Set<String> manyWords = setOf("this", "is", "an", "example");
+
+// Construct a double set
+Set<Double> manyValues = setOf(1.0D, 2.0D, 3.0D);
+```
+
+## mapOf
+
+Quickly construct an map of any type, equivalent to Kotlin's `mutableMapOf()` method.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.mapOf;
+import static com.alibaba.testable.core.tool.CollectionTool.entryOf;
+
+// Construct a string to string map
+Map<String, String> manyWords = mapOf(
+    entryOf("language", "java"),
+    entryOf("type", "unittest"),
+    entryOf("library", "testable")
+);
+
+// Construct a integer to double map
+Map<Integer, Double> manyValues = mapOf(
+    entryOf(1, 10.12D),
+    entryOf(2, 20.24D),
+    entryOf(3, 30.36D)
+);
+```
+
+## orderedMapOf
+
+Quickly construct ordered map (LinkedListMap) of any type. Compared with the HashMap map created by `mapOf()`, when traversing its keys or values in a loop, the order will always be the same as entries passed to `orderedMapOf()` method during construction.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.orderedMapOf;
+import static com.alibaba.testable.core.tool.CollectionTool.entryOf;
+
+// Construct a string to string ordered map
+Map<String, String> manyWords = orderedMapOf(
+    entryOf("language", "java"),
+    entryOf("type", "unittest"),
+    entryOf("library", "testable")
+);
+
+// Construct a integer to double ordered map
+Map<Integer, Double> manyValues = orderedMapOf(
+    entryOf(1, 10.12D),
+    entryOf(2, 20.24D),
+    entryOf(3, 30.36D)
+);
+```
+
+## entryOf
+
+Used with `mapOf()` and `orderedMapOf()` methods to construct a map.
+
+## slice
+
+Used to extract a part of data from any type of array to a new array.
+
+Usage example:
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.slice;
+import static com.alibaba.testable.core.tool.CollectionTool.arrayOf;
+
+// Extract the elements of the specified string array from subscript 1 to 3
+// the returned new array content are ["is", "a", "simple"]
+String[] fullWords = arrayOf("this", "is", "a", "simple", "example");
+String[] partOfWords = slice(fullWords, 1, 3);
+
+// If only given the index of starting position, all elements after this position are extracted
+// the new array returned in the following example is [5, 8, 13, 21]
+Integer[] fibonacci = arrayOf(1, 1, 2, 3, 5, 8, 13, 21);
+Integer[] partOfFibonacci = slice(fibonacci, 4);
+```

docs/en-us/doc/setup.md

@@ -7,6 +7,7 @@ Use TestableMock
 - [Access private members of the class under test](en-us/doc/private-accessor.md): enable unit tests directly invoke or access private members of the class under test, solve the problems of private member initialization and private method testing
 - [Quickly construct complicated parameter object](en-us/doc/omni-constructor.md)：generate arbitrarily nested object instances, simplify their internal member assignment methods, solve the problem of long initialization codes for method parameters
 - [Assist test void method](en-us/doc/test-void-method.md): use the mock validator to check the internal logic of method, solve the problem that unit testing is difficult to implement to the method with no return value
+- [Quickly create collection instances](en-us/doc/collection-tools.md): provide utility methods for collection creation, solve the problem of redundant codes during java test data preparation
 
 ## Use in Maven project
 

docs/en-us/sidebar.md

@@ -4,6 +4,7 @@
   - [Private Accessor](en-us/doc/private-accessor.md)
   - [Omni Constructor](en-us/doc/omni-constructor.md)
   - [Test Void Method](en-us/doc/test-void-method.md)
+  - [Collection Tools](en-us/doc/collection-tools.md)
 
 - Usage Guide
   - [Verify Mock Invocation](en-us/doc/invoke-matcher.md)

docs/zh-cn/doc/annotations.md

@@ -20,11 +20,14 @@
 
 - 作用于：Mock容器类中的方法
 
-| 参数          | 类型       | 是否必须 | 默认值           | 作用 |
-| ---          | ---       | ---     | ----             | ---  |
-| targetClass  | Class     | 否      | N/A              | 指定Mock目标的调用者类型 |
-| targetMethod | String    | 否      | N/A              | 指定Mock目标的方法名 |
-| scope        | MockScope | 否      | MockScope.GLOBAL | 指定Mock的生效范围 |
+| 参数            | 类型       | 是否必须 | 默认值           | 作用 |
+| ---             | ---       | ---     | ----             | ---  |
+| targetClass     | Class     | 否      | N/A              | 指定Mock目标的调用者类型 |
+| targetClassName | String    | 否      | N/A              | 与`targetClass`相同，主要用于无法直接引用的私有内部类 |
+| targetMethod    | String    | 否      | N/A              | 指定Mock目标的方法名 |
+| scope           | MockScope | 否      | MockScope.GLOBAL | 指定Mock的生效范围 |
+
+> 说明：`targetClass`和`targetClassName`参数不能同时使用
 
 #### @MockNew
 

docs/zh-cn/doc/collection-tools.md

@@ -0,0 +1,129 @@
+常用集合构建工具
+---
+
+在编写测试数据的时候，经常会用到各种集合类型的对象，然而Java原生的集合类型需要反复调用`add()`或`put()`方法来添加数据，使代码显得十分冗长。
+
+`TestableMock`借鉴了Kotlin语言简洁的集合构造方法，提供了一个实用的集合构造工具类`CollectionTool`，让Java集合对象的创建从此变得优雅。
+
+这个工具类提供了以下全局静态方法：
+
+## arrayOf
+
+快速构造任意类型的数组，等效于Kotlin的`arrayOf()`方法。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.arrayOf;
+
+// 构造一个字符串数组
+String[] manyWords = arrayOf("this", "is", "an", "example");
+
+// 构造一个浮点值数组
+Double[] manyValues = arrayOf(1.0D, 2.0D, 3.0D);
+```
+
+## listOf
+
+快速构造任意类型的列表，等效于Kotlin的`mutableListOf()`方法。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.listOf;
+
+// 构造一个字符串列表
+List<String> manyWords = listOf("this", "is", "an", "example");
+
+// 构造一个浮点值列表        
+List<Double> manyValues = listOf(1.0D, 2.0D, 3.0D);
+```
+
+## setOf
+
+快速构造任意类型的集合，等效于Kotlin的`mutableSetOf()`方法。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.setOf;
+
+// 构造一个字符串集合
+Set<String> manyWords = setOf("this", "is", "an", "example");
+
+// 构造一个浮点值集合
+Set<Double> manyValues = setOf(1.0D, 2.0D, 3.0D);
+```
+
+## mapOf
+
+快速构造任意类型的无序映射表，等效于Kotlin的`mutableMapOf()`方法。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.mapOf;
+import static com.alibaba.testable.core.tool.CollectionTool.entryOf;
+
+// 构造一个字符串到字符串的映射
+Map<String, String> manyWords = mapOf(
+    entryOf("language", "java"),
+    entryOf("type", "unittest"),
+    entryOf("library", "testable")
+);
+
+// 构造一个整型数值到浮点数值的映射
+Map<Integer, Double> manyValues = mapOf(
+    entryOf(1, 10.12D),
+    entryOf(2, 20.24D),
+    entryOf(3, 30.36D)
+);
+```
+
+## orderedMapOf
+
+快速构造任意类型的有序映射表（LinkedListMap），相较于`mapOf()`创建的HashMap对象，当在循环中遍历它的键或值列表时，其访问顺序始终会与构造时传给`orderedMapOf()`方法的数据顺序一致。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.orderedMapOf;
+import static com.alibaba.testable.core.tool.CollectionTool.entryOf;
+
+// 构造一个字符串到字符串的有序映射
+Map<String, String> manyWords = orderedMapOf(
+    entryOf("language", "java"),
+    entryOf("type", "unittest"),
+    entryOf("library", "testable")
+);
+
+// 构造一个整型数值到浮点数值的有序映射
+Map<Integer, Double> manyValues = orderedMapOf(
+    entryOf(1, 10.12D),
+    entryOf(2, 20.24D),
+    entryOf(3, 30.36D)
+);
+```
+
+## entryOf
+
+配合`mapOf()`和`orderedMapOf()`方法使用，用于构造映射表。
+
+## slice
+
+用于提取任意类型数组中间的一部分数据，组成新的数组。
+
+用法示例：
+
+```java
+import static com.alibaba.testable.core.tool.CollectionTool.slice;
+import static com.alibaba.testable.core.tool.CollectionTool.arrayOf;
+
+// 提取指定字符串数组从下标1到3之间的元素，得到的新数组内容为["is", "a", "simple"]
+String[] fullWords = arrayOf("this", "is", "a", "simple", "example");
+String[] partOfWords = slice(fullWords, 1, 3);
+
+// 只传入起始位置下标，提取该位置之后的所有元素，下例返回的新数组内容为[5, 8, 13, 21]
+Integer[] fibonacci = arrayOf(1, 1, 2, 3, 5, 8, 13, 21);
+Integer[] partOfFibonacci = slice(fibonacci, 4);
+```

docs/zh-cn/doc/setup.md

@@ -7,6 +7,7 @@
 - [访问被测类私有成员](zh-cn/doc/private-accessor.md)：使单元测试能直接调用和访问被测类的私有成员，解决私有成员初始化和私有方法测试的问题
 - [快速构造参数对象](zh-cn/doc/omni-constructor.md)：生成任意复杂嵌套的对象实例，并简化其内部成员赋值方式，解决被测方法参数初始化代码冗长的问题
 - [辅助测试void方法](zh-cn/doc/test-void-method.md)：利用Mock校验器对方法的内部逻辑进行检查，解决无返回值方法难以实施单元测试的问题
+- [快速构造集合对象](zh-cn/doc/collection-tools.md)：提供简洁易用的集合构造和常用操作方法，解决准备测试数据时Java集合初始化代码冗长的问题
 
 ## 在Maven项目中使用
 

docs/zh-cn/sidebar.md

@@ -4,6 +4,7 @@
   - [直接访问私有成员](zh-cn/doc/private-accessor.md)
   - [快速构造复杂入参](zh-cn/doc/omni-constructor.md)
   - [测试无返回值的方法](zh-cn/doc/test-void-method.md)
+  - [常用集合构建工具](zh-cn/doc/collection-tools.md)
 
 - 使用指南
   - [校验Mock调用](zh-cn/doc/invoke-matcher.md)