docs: 完善 collection 包部分文档

utils/collection/README.md

@@ -19,9 +19,9 @@ collection 定义了各种对于集合操作有用的各种函数
 |[CloneSlice](#CloneSlice)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片
 |[CloneMap](#CloneMap)|通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map
 |[CloneSliceN](#CloneSliceN)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片
-|[CloneMapN](#CloneMapN)|克隆 map 为 n 个 map 进行返回
-|[CloneSlices](#CloneSlices)|克隆多个切片
-|[CloneMaps](#CloneMaps)|克隆多个 map
+|[CloneMapN](#CloneMapN)|通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map
+|[CloneSlices](#CloneSlices)|对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片
+|[CloneMaps](#CloneMaps)|对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片
 |[InSlice](#InSlice)|检查 v 是否被包含在 slice 中，当 handler 返回 true 时，表示 v 和 slice 中的某个元素相匹配
 |[InComparableSlice](#InComparableSlice)|检查 v 是否被包含在 slice 中
 |[AllInSlice](#AllInSlice)|检查 values 中的所有元素是否均被包含在 slice 中，当 handler 返回 true 时，表示 values 中的某个元素和 slice 中的某个元素相匹配
@@ -133,8 +133,8 @@ collection 定义了各种对于集合操作有用的各种函数
 
 |类型|名称|描述
 |:--|:--|:--
-|`STRUCT`|[ComparisonHandler](#struct_ComparisonHandler)|暂无描述...
-|`STRUCT`|[OrderedValueGetter](#struct_OrderedValueGetter)|暂无描述...
+|`STRUCT`|[ComparisonHandler](#struct_ComparisonHandler)|用于比较 `source` 和 `target` 两个值是否相同的比较函数
+|`STRUCT`|[OrderedValueGetter](#struct_OrderedValueGetter)|用于获取 v 的可排序字段值的函数
 
 </details>
 
@@ -314,10 +314,16 @@ func TestCloneSliceN(t *testing.T) {
 ***
 #### func CloneMapN\[M ~map[K]V, K comparable, V any\](m M, n int) []M
 <span id="CloneMapN"></span>
-> 克隆 map 为 n 个 map 进行返回
+> 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map
+>   - 当 m 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片
 
 **示例代码：**
 
+map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址
+  - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对`
+  - 示例中的结果将会输出 2
+
+
 ```go
 
 func ExampleCloneMapN() {
@@ -370,10 +376,16 @@ func TestCloneMapN(t *testing.T) {
 ***
 #### func CloneSlices\[S ~[]V, V any\](slices ...S) []S
 <span id="CloneSlices"></span>
-> 克隆多个切片
+> 对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片
+>   - 当 slices 为空时，将会返回 nil
+>   - 该函数相当于使用 CloneSlice 函数一次性对多个切片进行克隆
 
 **示例代码：**
 
+slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址
+  - result 的结果为 [[1 2 3] [1 2 3]]
+
+
 ```go
 
 func ExampleCloneSlices() {
@@ -423,10 +435,16 @@ func TestCloneSlices(t *testing.T) {
 ***
 #### func CloneMaps\[M ~map[K]V, K comparable, V any\](maps ...M) []M
 <span id="CloneMaps"></span>
-> 克隆多个 map
+> 对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片
+>   - 当 maps 为空时，将会返回 nil
+>   - 该函数相当于使用 CloneMap 函数一次性对多个 map 进行克隆
 
 **示例代码：**
 
+map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址
+  - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对`
+
+
 ```go
 
 func ExampleCloneMaps() {
@@ -5539,13 +5557,14 @@ func TestShuffleByClone(t *testing.T) {
 ***
 <span id="struct_ComparisonHandler"></span>
 ### ComparisonHandler `STRUCT`
-
+用于比较 `source` 和 `target` 两个值是否相同的比较函数
+  - 该函数接受两个参数，分别是源值和目标值，返回 true 的情况下即表示两者相同
 ```go
 type ComparisonHandler[V any] func(source V) bool
 ```
 <span id="struct_OrderedValueGetter"></span>
 ### OrderedValueGetter `STRUCT`
-
+用于获取 v 的可排序字段值的函数
 ```go
 type OrderedValueGetter[V any, N generic.Ordered] func(v V) N
 ```

utils/collection/clone.go

@@ -40,7 +40,8 @@ func CloneSliceN[S ~[]V, V any](slice S, n int) []S {
 	return result
 }
 
-// CloneMapN 克隆 map 为 n 个 map 进行返回
+// CloneMapN 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map
+//   - 当 m 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片
 func CloneMapN[M ~map[K]V, K comparable, V any](m M, n int) []M {
 	if m == nil {
 		return nil
@@ -57,7 +58,9 @@ func CloneMapN[M ~map[K]V, K comparable, V any](m M, n int) []M {
 	return result
 }
 
-// CloneSlices 克隆多个切片
+// CloneSlices 对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片
+//   - 当 slices 为空时，将会返回 nil
+//   - 该函数相当于使用 CloneSlice 函数一次性对多个切片进行克隆
 func CloneSlices[S ~[]V, V any](slices ...S) []S {
 	if slices == nil {
 		return nil
@@ -70,7 +73,9 @@ func CloneSlices[S ~[]V, V any](slices ...S) []S {
 	return result
 }
 
-// CloneMaps 克隆多个 map
+// CloneMaps 对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片
+//   - 当 maps 为空时，将会返回 nil
+//   - 该函数相当于使用 CloneMap 函数一次性对多个 map 进行克隆
 func CloneMaps[M ~map[K]V, K comparable, V any](maps ...M) []M {
 	if maps == nil {
 		return nil

utils/collection/clone_example_test.go

@@ -36,6 +36,9 @@ func ExampleCloneSliceN() {
 	// 2
 }
 
+// 通过将 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址
+//   - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对`
+//   - 示例中的结果将会输出 2
 func ExampleCloneMapN() {
 	var m = map[int]int{1: 1, 2: 2, 3: 3}
 	var result = collection.CloneMapN(m, 2)
@@ -44,6 +47,8 @@ func ExampleCloneMapN() {
 	// 2
 }
 
+// 通过将多个 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址
+//   - result 的结果为 [[1 2 3] [1 2 3]]
 func ExampleCloneSlices() {
 	var slice1 = []int{1, 2, 3}
 	var slice2 = []int{1, 2, 3}
@@ -53,6 +58,8 @@ func ExampleCloneSlices() {
 	// 2
 }
 
+// 通过将多个 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址
+//   - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对`
 func ExampleCloneMaps() {
 	var m1 = map[int]int{1: 1, 2: 2, 3: 3}
 	var m2 = map[int]int{1: 1, 2: 2, 3: 3}

utils/collection/collection.go

@@ -2,5 +2,9 @@ package collection
 
 import "github.com/kercylan98/minotaur/utils/generic"
 
+// ComparisonHandler 用于比较 `source` 和 `target` 两个值是否相同的比较函数
+//   - 该函数接受两个参数，分别是源值和目标值，返回 true 的情况下即表示两者相同
 type ComparisonHandler[V any] func(source, target V) bool
+
+// OrderedValueGetter 用于获取 v 的可排序字段值的函数
 type OrderedValueGetter[V any, N generic.Ordered] func(v V) N