From 580bab2dfc847096fdc380a692fa5fc5bbbd63ec Mon Sep 17 00:00:00 2001 From: kercylan98 Date: Mon, 15 Jan 2024 11:12:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=20README.md=20?= =?UTF-8?q?=E7=9A=84=E6=B5=8B=E8=AF=95=E7=94=A8=E4=BE=8B=E6=8F=8F=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- game/space/README.md | 3 +- server/README.md | 9 +- server/internal/dispatcher/README.md | 6 +- server/router/README.md | 15 +- server/writeloop/README.md | 3 +- utils/collection/README.md | 342 +++++++++++++++++-------- utils/collection/clone.go | 3 +- utils/collection/clone_example_test.go | 7 + utils/generator/astgo/function.go | 3 + utils/generator/genreadme/builder.go | 42 ++- utils/geometry/README.md | 30 ++- utils/geometry/astar/README.md | 3 +- utils/geometry/navmesh/README.md | 3 +- utils/hub/README.md | 3 +- utils/leaderboard/README.md | 3 +- utils/maths/README.md | 6 +- utils/moving/README.md | 3 +- utils/sorts/README.md | 3 +- utils/super/README.md | 12 +- utils/times/README.md | 3 +- 20 files changed, 351 insertions(+), 151 deletions(-) diff --git a/game/space/README.md b/game/space/README.md index 4b239fb..cb4d152 100644 --- a/game/space/README.md +++ b/game/space/README.md @@ -38,7 +38,8 @@ space 游戏中常见的空间设计，例如房间、地图等 > 创建房间管理器 RoomManager 的实例 -示例代码： +**示例代码：** + ```go func ExampleNewRoomManager() { diff --git a/server/README.md b/server/README.md index 80226cc..fe320bc 100644 --- a/server/README.md +++ b/server/README.md @@ -300,7 +300,8 @@ func TestNewBot(t *testing.T) { > 根据特定网络类型创建一个服务器 -示例代码： +**示例代码：** + ```go func ExampleNew() { @@ -351,7 +352,8 @@ func TestNew(t *testing.T) { > 绑定服务到特定 Server，被绑定的服务将会在 Server 初始化时执行 Service.OnInit 方法 -示例代码： +**示例代码：** + ```go func ExampleBindService() { @@ -860,7 +862,8 @@ type Server struct { > - server.NetworkWebsocket (addr:":8888/ws") > - server.NetworkKcp (addr:":8888") > - server.NetworkNone (addr:"") -示例代码： +**示例代码：** + ```go func ExampleServer_Run() { diff --git a/server/internal/dispatcher/README.md b/server/internal/dispatcher/README.md index 3948e8b..ec7fb12 100644 --- a/server/internal/dispatcher/README.md +++ b/server/internal/dispatcher/README.md @@ -40,7 +40,8 @@ > 创建一个新的消息分发器 Dispatcher 实例 -示例代码： +**示例代码：** + ```go func ExampleNewDispatcher() { @@ -111,7 +112,8 @@ func TestNewDispatcher(t *testing.T) { > 生成消息分发器管理器 -示例代码： +**示例代码：** + ```go func ExampleNewManager() { diff --git a/server/router/README.md b/server/router/README.md index 56e4248..993cbc5 100644 --- a/server/router/README.md +++ b/server/router/README.md @@ -37,7 +37,8 @@ > 创建一个支持多级分类的路由器 -示例代码： +**示例代码：** + ```go func ExampleNewMultistage() { @@ -76,7 +77,8 @@ type Multistage[HandleFunc any] struct { #### func (*Multistage) Register(routes ...any) MultistageBind[HandleFunc] > 注册路由是结合 Sub 和 Route 的快捷方式，用于一次性注册多级路由 > - 该函数将返回一个注册函数，可通过调用其将路由绑定到特定处理函数，例如：router.Register("a", "b").Bind(onExec()) -示例代码： +**示例代码：** + ```go func ExampleMultistage_Register() { @@ -90,7 +92,8 @@ func ExampleMultistage_Register() { *** #### func (*Multistage) Route(route any, handleFunc HandleFunc) > 为特定路由绑定处理函数，被绑定的处理函数将可以通过 Match 函数进行匹配 -示例代码： +**示例代码：** + ```go func ExampleMultistage_Route() { @@ -105,7 +108,8 @@ func ExampleMultistage_Route() { #### func (*Multistage) Match(routes ...any) HandleFunc > 匹配已绑定处理函数的路由，返回处理函数 > - 如果未找到将会返回空指针 -示例代码： +**示例代码：** + ```go func ExampleMultistage_Match() { @@ -154,7 +158,8 @@ func TestMultistage_Match(t *testing.T) { *** #### func (*Multistage) Sub(route any) *Multistage[HandleFunc] > 获取子路由器 -示例代码： +**示例代码：** + ```go func ExampleMultistage_Sub() { diff --git a/server/writeloop/README.md b/server/writeloop/README.md index 3b4d67b..3395e2d 100644 --- a/server/writeloop/README.md +++ b/server/writeloop/README.md @@ -53,7 +53,8 @@ > > 传入 writeHandler 的消息对象是从 pool 中获取的，并且在 writeHandler 执行完成后会被放回 pool 中，因此 writeHandler 不应该持有消息对象的引用，同时也不应该主动释放消息对象 -示例代码： +**示例代码：** + ```go func ExampleNewUnbounded() { diff --git a/utils/collection/README.md b/utils/collection/README.md index 5c3a13c..6b59b43 100644 --- a/utils/collection/README.md +++ b/utils/collection/README.md @@ -18,7 +18,7 @@ collection 定义了各种对于集合操作有用的各种函数 |:--|:-- |[CloneSlice](#CloneSlice)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片 |[CloneMap](#CloneMap)|通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map -|[CloneSliceN](#CloneSliceN)|克隆 slice 为 n 个切片进行返回 +|[CloneSliceN](#CloneSliceN)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 |[CloneMapN](#CloneMapN)|克隆 map 为 n 个 map 进行返回 |[CloneSlices](#CloneSlices)|克隆多个切片 |[CloneMaps](#CloneMaps)|克隆多个 map @@ -145,7 +145,12 @@ collection 定义了各种对于集合操作有用的各种函数 > 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片 -示例代码： +**示例代码：** + +slice 克隆后将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 + - 示例中的结果将会输出 [1 2 3] + + ```go func ExampleCloneSlice() { @@ -195,7 +200,8 @@ func TestCloneSlice(t *testing.T) { > 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map > - 当 m 为空时，将会返回 nil -示例代码： +**示例代码：** + ```go func ExampleCloneMap() { @@ -242,9 +248,11 @@ func TestCloneMap(t *testing.T) { *** #### func CloneSliceN\[S ~[]V, V any\](slice S, n int) []S -> 克隆 slice 为 n 个切片进行返回 +> 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 +> - 当 slice 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 + +**示例代码：** -示例代码： ```go func ExampleCloneSliceN() { @@ -299,7 +307,8 @@ func TestCloneSliceN(t *testing.T) { > 克隆 map 为 n 个 map 进行返回 -示例代码： +**示例代码：** + ```go func ExampleCloneMapN() { @@ -354,7 +363,8 @@ func TestCloneMapN(t *testing.T) { > 克隆多个切片 -示例代码： +**示例代码：** + ```go func ExampleCloneSlices() { @@ -406,7 +416,8 @@ func TestCloneSlices(t *testing.T) { > 克隆多个 map -示例代码： +**示例代码：** + ```go func ExampleCloneMaps() { @@ -458,7 +469,8 @@ func TestCloneMaps(t *testing.T) { > 检查 v 是否被包含在 slice 中，当 handler 返回 true 时，表示 v 和 slice 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleInSlice() { @@ -506,7 +518,8 @@ func TestInSlice(t *testing.T) { > 检查 v 是否被包含在 slice 中 -示例代码： +**示例代码：** + ```go func ExampleInComparableSlice() { @@ -552,7 +565,8 @@ func TestInComparableSlice(t *testing.T) { > - 在所有 values 中的元素都被包含在 slice 中时，返回 true > - 当 values 长度为 0 或为 nil 时，将返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInSlice() { @@ -602,7 +616,8 @@ func TestAllInSlice(t *testing.T) { > - 在所有 values 中的元素都被包含在 slice 中时，返回 true > - 当 values 长度为 0 或为 nil 时，将返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInComparableSlice() { @@ -647,7 +662,8 @@ func TestAllInComparableSlice(t *testing.T) { > 检查 values 中的任意一个元素是否被包含在 slice 中，当 handler 返回 true 时，表示 value 中的某个元素和 slice 中的某个元素相匹配 > - 当 values 中的任意一个元素被包含在 slice 中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInSlice() { @@ -696,7 +712,8 @@ func TestAnyInSlice(t *testing.T) { > 检查 values 中的任意一个元素是否被包含在 slice 中 > - 当 values 中的任意一个元素被包含在 slice 中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInComparableSlice() { @@ -741,7 +758,8 @@ func TestAnyInComparableSlice(t *testing.T) { > 通过将多个切片合并后检查 v 是否被包含在 slices 中，当 handler 返回 true 时，表示 v 和 slices 中的某个元素相匹配 > - 当传入的 v 被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInSlices() { @@ -790,7 +808,8 @@ func TestInSlices(t *testing.T) { > 通过将多个切片合并后检查 v 是否被包含在 slices 中 > - 当传入的 v 被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInComparableSlices() { @@ -835,7 +854,8 @@ func TestInComparableSlices(t *testing.T) { > 通过将多个切片合并后检查 values 中的所有元素是否被包含在 slices 中，当 handler 返回 true 时，表示 values 中的某个元素和 slices 中的某个元素相匹配 > - 当 values 中的所有元素都被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInSlices() { @@ -884,7 +904,8 @@ func TestAllInSlices(t *testing.T) { > 通过将多个切片合并后检查 values 中的所有元素是否被包含在 slices 中 > - 当 values 中的所有元素都被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInComparableSlices() { @@ -929,7 +950,8 @@ func TestAllInComparableSlices(t *testing.T) { > 通过将多个切片合并后检查 values 中的任意一个元素是否被包含在 slices 中，当 handler 返回 true 时，表示 values 中的某个元素和 slices 中的某个元素相匹配 > - 当 values 中的任意一个元素被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInSlices() { @@ -978,7 +1000,8 @@ func TestAnyInSlices(t *testing.T) { > 通过将多个切片合并后检查 values 中的任意一个元素是否被包含在 slices 中 > - 当 values 中的任意一个元素被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInComparableSlices() { @@ -1023,7 +1046,8 @@ func TestAnyInComparableSlices(t *testing.T) { > 检查 v 是否被包含在 slices 的每一项元素中，当 handler 返回 true 时，表示 v 和 slices 中的某个元素相匹配 > - 当 v 被包含在 slices 的每一项元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInAllSlices() { @@ -1072,7 +1096,8 @@ func TestInAllSlices(t *testing.T) { > 检查 v 是否被包含在 slices 的每一项元素中 > - 当 v 被包含在 slices 的每一项元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInAllComparableSlices() { @@ -1117,7 +1142,8 @@ func TestInAllComparableSlices(t *testing.T) { > 检查 slices 中的每一个元素是否均包含至少任意一个 values 中的元素，当 handler 返回 true 时，表示 value 中的某个元素和 slices 中的某个元素相匹配 > - 当 slices 中的每一个元素均包含至少任意一个 values 中的元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInAllSlices() { @@ -1166,7 +1192,8 @@ func TestAnyInAllSlices(t *testing.T) { > 检查 slices 中的每一个元素是否均包含至少任意一个 values 中的元素 > - 当 slices 中的每一个元素均包含至少任意一个 values 中的元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInAllComparableSlices() { @@ -1210,7 +1237,8 @@ func TestAnyInAllComparableSlices(t *testing.T) { > 检查 m 中是否包含特定 key -示例代码： +**示例代码：** + ```go func ExampleKeyInMap() { @@ -1254,7 +1282,8 @@ func TestKeyInMap(t *testing.T) { > 检查 m 中是否包含特定 value，当 handler 返回 true 时，表示 value 和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleValueInMap() { @@ -1301,7 +1330,8 @@ func TestValueInMap(t *testing.T) { > 检查 m 中是否包含 keys 中所有的元素 -示例代码： +**示例代码：** + ```go func ExampleAllKeyInMap() { @@ -1345,7 +1375,8 @@ func TestAllKeyInMap(t *testing.T) { > 检查 m 中是否包含 values 中所有的元素，当 handler 返回 true 时，表示 values 中的某个元素和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAllValueInMap() { @@ -1391,7 +1422,8 @@ func TestAllValueInMap(t *testing.T) { > 检查 m 中是否包含 keys 中任意一个元素 -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInMap() { @@ -1435,7 +1467,8 @@ func TestAnyKeyInMap(t *testing.T) { > 检查 m 中是否包含 values 中任意一个元素，当 handler 返回 true 时，表示 values 中的某个元素和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAnyValueInMap() { @@ -1481,7 +1514,8 @@ func TestAnyValueInMap(t *testing.T) { > 检查 maps 中的每一个元素是否均包含 keys 中所有的元素 -示例代码： +**示例代码：** + ```go func ExampleAllKeyInMaps() { @@ -1525,7 +1559,8 @@ func TestAllKeyInMaps(t *testing.T) { > 检查 maps 中的每一个元素是否均包含 value 中所有的元素，当 handler 返回 true 时，表示 value 中的某个元素和 maps 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAllValueInMaps() { @@ -1572,7 +1607,8 @@ func TestAllValueInMaps(t *testing.T) { > 检查 keys 中的任意一个元素是否被包含在 maps 中的任意一个元素中 > - 当 keys 中的任意一个元素被包含在 maps 中的任意一个元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInMaps() { @@ -1617,7 +1653,8 @@ func TestAnyKeyInMaps(t *testing.T) { > 检查 maps 中的任意一个元素是否包含 value 中的任意一个元素，当 handler 返回 true 时，表示 value 中的某个元素和 maps 中的某个元素相匹配 > - 当 maps 中的任意一个元素包含 value 中的任意一个元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyValueInMaps() { @@ -1663,7 +1700,8 @@ func TestAnyValueInMaps(t *testing.T) { > 检查 key 是否被包含在 maps 的每一个元素中 -示例代码： +**示例代码：** + ```go func ExampleKeyInAllMaps() { @@ -1708,7 +1746,8 @@ func TestKeyInAllMaps(t *testing.T) { > 检查 maps 中的每一个元素是否均包含 keys 中任意一个元素 > - 当 maps 中的每一个元素均包含 keys 中任意一个元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInAllMaps() { @@ -1752,7 +1791,8 @@ func TestAnyKeyInAllMaps(t *testing.T) { > 将切片转换为任意类型的切片 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToAny() { @@ -1804,7 +1844,8 @@ func TestConvertSliceToAny(t *testing.T) { > 将切片转换为索引为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToIndexMap() { @@ -1855,7 +1896,8 @@ func TestConvertSliceToIndexMap(t *testing.T) { > 将切片转换为索引为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToIndexOnlyMap() { @@ -1910,7 +1952,8 @@ func TestConvertSliceToIndexOnlyMap(t *testing.T) { > 将切片转换为值为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToMap() { @@ -1962,7 +2005,8 @@ func TestConvertSliceToMap(t *testing.T) { > 将切片转换为值为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToBoolMap() { @@ -2013,7 +2057,8 @@ func TestConvertSliceToBoolMap(t *testing.T) { > 将映射的键转换为切片 -示例代码： +**示例代码：** + ```go func ExampleConvertMapKeysToSlice() { @@ -2069,7 +2114,8 @@ func TestConvertMapKeysToSlice(t *testing.T) { > 将映射的值转换为切片 -示例代码： +**示例代码：** + ```go func ExampleConvertMapValuesToSlice() { @@ -2126,7 +2172,8 @@ func TestConvertMapValuesToSlice(t *testing.T) { > 将映射的键和值互换 -示例代码： +**示例代码：** + ```go func ExampleInvertMap() { @@ -2174,7 +2221,8 @@ func TestInvertMap(t *testing.T) { > 将映射的值转换为布尔值 -示例代码： +**示例代码：** + ```go func ExampleConvertMapValuesToBool() { @@ -2222,7 +2270,8 @@ func TestConvertMapValuesToBool(t *testing.T) { > 将切片反转 -示例代码： +**示例代码：** + ```go func ExampleReverseSlice() { @@ -2275,7 +2324,8 @@ func TestReverseSlice(t *testing.T) { > 清空切片 -示例代码： +**示例代码：** + ```go func ExampleClearSlice() { @@ -2324,7 +2374,8 @@ func TestClearSlice(t *testing.T) { > 清空 map -示例代码： +**示例代码：** + ```go func ExampleClearMap() { @@ -2373,7 +2424,8 @@ func TestClearMap(t *testing.T) { > 删除切片中特定索引的元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceByIndices() { @@ -2424,7 +2476,8 @@ func TestDropSliceByIndices(t *testing.T) { > 删除切片中符合条件的元素 > - condition 的返回值为 true 时，将会删除该元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceByCondition() { @@ -2484,7 +2537,8 @@ func TestDropSliceByCondition(t *testing.T) { > 删除切片中与另一个切片重叠的元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceOverlappingElements() { @@ -2547,7 +2601,8 @@ func TestDropSliceOverlappingElements(t *testing.T) { > 去除切片中的重复元素 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceInPlace() { @@ -2597,7 +2652,8 @@ func TestDeduplicateSliceInPlace(t *testing.T) { > 去除切片中的重复元素，返回新切片 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSlice() { @@ -2646,7 +2702,8 @@ func TestDeduplicateSlice(t *testing.T) { > 去除切片中的重复元素，使用自定义的比较函数 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceInPlaceWithCompare() { @@ -2700,7 +2757,8 @@ func TestDeduplicateSliceInPlaceWithCompare(t *testing.T) { > 去除切片中的重复元素，使用自定义的比较函数，返回新的切片 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceWithCompare() { @@ -2753,7 +2811,8 @@ func TestDeduplicateSliceWithCompare(t *testing.T) { > 过滤切片中特定索引的元素，返回过滤后的切片 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByIndices() { @@ -2804,7 +2863,8 @@ func TestFilterOutByIndices(t *testing.T) { > 过滤切片中符合条件的元素，返回过滤后的切片 > - condition 的返回值为 true 时，将会过滤掉该元素 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByCondition() { @@ -2862,7 +2922,8 @@ func TestFilterOutByCondition(t *testing.T) { > 过滤 map 中特定的 key，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByKey() { @@ -2912,7 +2973,8 @@ func TestFilterOutByKey(t *testing.T) { > 过滤 map 中特定的 value，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByValue() { @@ -2966,7 +3028,8 @@ func TestFilterOutByValue(t *testing.T) { > 过滤 map 中多个 key，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByKeys() { @@ -3016,7 +3079,8 @@ func TestFilterOutByKeys(t *testing.T) { > 过滤 map 中多个 values，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByValues() { @@ -3073,7 +3137,8 @@ func TestFilterOutByValues(t *testing.T) { > 过滤 map 中符合条件的元素，返回过滤后的 map > - condition 的返回值为 true 时，将会过滤掉该元素 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByMap() { @@ -3128,7 +3193,8 @@ func TestFilterOutByMap(t *testing.T) { > 返回 i 的下一个数组成员，当 i 达到数组长度时从 0 开始 > - 当 i 为负数时将返回第一个元素 -示例代码： +**示例代码：** + ```go func ExampleFindLoopedNextInSlice() { @@ -3173,7 +3239,8 @@ func TestFindLoopedNextInSlice(t *testing.T) { > 返回 i 的上一个数组成员，当 i 为 0 时从数组末尾开始 > - 当 i 为负数时将返回最后一个元素 -示例代码： +**示例代码：** + ```go func ExampleFindLoopedPrevInSlice() { @@ -3217,7 +3284,8 @@ func TestFindLoopedPrevInSlice(t *testing.T) { > 获取给定数组的所有组合，且每个组合的成员数量限制在指定范围内 -示例代码： +**示例代码：** + ```go func ExampleFindCombinationsInSliceByRange() { @@ -3262,7 +3330,8 @@ func TestFindCombinationsInSliceByRange(t *testing.T) { > 判断切片中是否存在元素，返回第一个元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindFirstOrDefaultInSlice() { @@ -3305,7 +3374,8 @@ func TestFindFirstOrDefaultInSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindOrDefaultInSlice() { @@ -3352,7 +3422,8 @@ func TestFindOrDefaultInSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindOrDefaultInComparableSlice() { @@ -3395,7 +3466,8 @@ func TestFindOrDefaultInComparableSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindInSlice() { @@ -3442,7 +3514,8 @@ func TestFindInSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindIndexInSlice() { @@ -3489,7 +3562,8 @@ func TestFindIndexInSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindInComparableSlice() { @@ -3532,7 +3606,8 @@ func TestFindInComparableSlice(t *testing.T) { > 判断切片中是否存在某个元素，返回第一个匹配的索引，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindIndexInComparableSlice() { @@ -3575,7 +3650,8 @@ func TestFindIndexInComparableSlice(t *testing.T) { > 获取切片中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinimumInComparableSlice() { @@ -3618,7 +3694,8 @@ func TestFindMinimumInComparableSlice(t *testing.T) { > 获取切片中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinimumInSlice() { @@ -3665,7 +3742,8 @@ func TestFindMinimumInSlice(t *testing.T) { > 获取切片中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaximumInComparableSlice() { @@ -3708,7 +3786,8 @@ func TestFindMaximumInComparableSlice(t *testing.T) { > 获取切片中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaximumInSlice() { @@ -3755,7 +3834,8 @@ func TestFindMaximumInSlice(t *testing.T) { > 获取切片中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxInComparableSlice() { @@ -3799,7 +3879,8 @@ func TestFindMin2MaxInComparableSlice(t *testing.T) { > 获取切片中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxInSlice() { @@ -3847,7 +3928,8 @@ func TestFindMin2MaxInSlice(t *testing.T) { > 获取 map 中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinFromComparableMap() { @@ -3890,7 +3972,8 @@ func TestFindMinFromComparableMap(t *testing.T) { > 获取 map 中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinFromMap() { @@ -3937,7 +4020,8 @@ func TestFindMinFromMap(t *testing.T) { > 获取 map 中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaxFromComparableMap() { @@ -3980,7 +4064,8 @@ func TestFindMaxFromComparableMap(t *testing.T) { > 获取 map 中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaxFromMap() { @@ -4027,7 +4112,8 @@ func TestFindMaxFromMap(t *testing.T) { > 获取 map 中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxFromComparableMap() { @@ -4071,7 +4157,8 @@ func TestFindMin2MaxFromComparableMap(t *testing.T) { > 获取 map 中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxFromMap() { @@ -4115,7 +4202,8 @@ func TestFindMin2MaxFromMap(t *testing.T) { > 将切片中的两个元素进行交换 -示例代码： +**示例代码：** + ```go func ExampleSwapSlice() { @@ -4163,7 +4251,8 @@ func TestSwapSlice(t *testing.T) { > 将切片中的元素进行转换 -示例代码： +**示例代码：** + ```go func ExampleMappingFromSlice() { @@ -4215,7 +4304,8 @@ func TestMappingFromSlice(t *testing.T) { > 将 map 中的元素进行转换 -示例代码： +**示例代码：** + ```go func ExampleMappingFromMap() { @@ -4267,7 +4357,8 @@ func TestMappingFromMap(t *testing.T) { > 合并切片 -示例代码： +**示例代码：** + ```go func ExampleMergeSlices() { @@ -4314,7 +4405,8 @@ func TestMergeSlices(t *testing.T) { > 合并 map，当多个 map 中存在相同的 key 时，后面的 map 中的 key 将会覆盖前面的 map 中的 key -示例代码： +**示例代码：** + ```go func ExampleMergeMaps() { @@ -4357,7 +4449,8 @@ func TestMergeMaps(t *testing.T) { > 合并 map，当多个 map 中存在相同的 key 时，后面的 map 中的 key 将会被跳过 -示例代码： +**示例代码：** + ```go func ExampleMergeMapsWithSkip() { @@ -4401,7 +4494,8 @@ func TestMergeMapsWithSkip(t *testing.T) { > 返回 slice 中的 n 个可重复随机元素 > - 当 slice 长度为 0 或 n 小于等于 0 时将会返回 nil -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElementRepeatN() { @@ -4445,7 +4539,8 @@ func TestChooseRandomSliceElementRepeatN(t *testing.T) { > 返回 slice 中的 n 个可重复随机元素的索引 > - 当 slice 长度为 0 或 n 小于等于 0 时将会返回 nil -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndexRepeatN() { @@ -4488,7 +4583,8 @@ func TestChooseRandomIndexRepeatN(t *testing.T) { > 返回 slice 中随机一个元素，当 slice 长度为 0 时将会得到 V 的零值 -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElement() { @@ -4531,7 +4627,8 @@ func TestChooseRandomSliceElement(t *testing.T) { > 返回 slice 中随机一个元素的索引，当 slice 长度为 0 时将会得到 -1 -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndex() { @@ -4575,7 +4672,8 @@ func TestChooseRandomIndex(t *testing.T) { > 返回 slice 中的 n 个不可重复的随机元素 > - 当 slice 长度为 0 或 n 大于 slice 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElementN() { @@ -4618,7 +4716,8 @@ func TestChooseRandomSliceElementN(t *testing.T) { > 获取切片中的 n 个随机元素的索引 > - 如果 n 大于切片长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndexN() { @@ -4662,7 +4761,8 @@ func TestChooseRandomIndexN(t *testing.T) { > 获取 map 中的 n 个随机 key，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyRepeatN() { @@ -4706,7 +4806,8 @@ func TestChooseRandomMapKeyRepeatN(t *testing.T) { > 获取 map 中的 n 个随机 n，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValueRepeatN() { @@ -4750,7 +4851,8 @@ func TestChooseRandomMapValueRepeatN(t *testing.T) { > 获取 map 中的 n 个随机 key 和 v，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValueRepeatN() { @@ -4793,7 +4895,8 @@ func TestChooseRandomMapKeyAndValueRepeatN(t *testing.T) { > 获取 map 中的随机 key -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKey() { @@ -4836,7 +4939,8 @@ func TestChooseRandomMapKey(t *testing.T) { > 获取 map 中的随机 value -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValue() { @@ -4880,7 +4984,8 @@ func TestChooseRandomMapValue(t *testing.T) { > 获取 map 中的 inputN 个随机 key > - 如果 inputN 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyN() { @@ -4896,7 +5001,8 @@ func ExampleChooseRandomMapKeyN() { > 获取 map 中的 n 个随机 value > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValueN() { @@ -4939,7 +5045,8 @@ func TestChooseRandomMapValueN(t *testing.T) { > 获取 map 中的随机 key 和 v -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValue() { @@ -4983,7 +5090,8 @@ func TestChooseRandomMapKeyAndValue(t *testing.T) { > 获取 map 中的 inputN 个随机 key 和 v > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValueN() { @@ -5028,7 +5136,8 @@ func TestChooseRandomMapKeyAndValueN(t *testing.T) { > 返回降序比较结果 -示例代码： +**示例代码：** + ```go func ExampleDescBy() { @@ -5078,7 +5187,8 @@ func TestDescBy(t *testing.T) { > 返回升序比较结果 -示例代码： +**示例代码：** + ```go func ExampleAscBy() { @@ -5128,7 +5238,8 @@ func TestAscBy(t *testing.T) { > 对切片进行降序排序 -示例代码： +**示例代码：** + ```go func ExampleDesc() { @@ -5178,7 +5289,8 @@ func TestDesc(t *testing.T) { > 对切片进行降序排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleDescByClone() { @@ -5228,7 +5340,8 @@ func TestDescByClone(t *testing.T) { > 对切片进行升序排序 -示例代码： +**示例代码：** + ```go func ExampleAsc() { @@ -5278,7 +5391,8 @@ func TestAsc(t *testing.T) { > 对切片进行升序排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleAscByClone() { @@ -5328,7 +5442,8 @@ func TestAscByClone(t *testing.T) { > 对切片进行随机排序 -示例代码： +**示例代码：** + ```go func ExampleShuffle() { @@ -5372,7 +5487,8 @@ func TestShuffle(t *testing.T) { > 对切片进行随机排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleShuffleByClone() { diff --git a/utils/collection/clone.go b/utils/collection/clone.go index 44400ce..d648b81 100644 --- a/utils/collection/clone.go +++ b/utils/collection/clone.go @@ -23,7 +23,8 @@ func CloneMap[M ~map[K]V, K comparable, V any](m M) M { return result } -// CloneSliceN 克隆 slice 为 n 个切片进行返回 +// CloneSliceN 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 +// - 当 slice 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 func CloneSliceN[S ~[]V, V any](slice S, n int) []S { if slice == nil { return nil diff --git a/utils/collection/clone_example_test.go b/utils/collection/clone_example_test.go index e5e00ed..9760ac0 100644 --- a/utils/collection/clone_example_test.go +++ b/utils/collection/clone_example_test.go @@ -5,6 +5,8 @@ import ( "github.com/kercylan98/minotaur/utils/collection" ) +// 在该示例中，将 slice 克隆后将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 +// - 示例中的结果将会输出 [1 2 3] func ExampleCloneSlice() { var slice = []int{1, 2, 3} var result = collection.CloneSlice(slice) @@ -13,6 +15,8 @@ func ExampleCloneSlice() { // [1 2 3] } +// 在该示例中，将 map 克隆后将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 +// - 示例中的结果将会输出 3 func ExampleCloneMap() { var m = map[int]int{1: 1, 2: 2, 3: 3} var result = collection.CloneMap(m) @@ -21,6 +25,9 @@ func ExampleCloneMap() { // 3 } +// 通过将 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 +// - result 的结果为 [[1 2 3] [1 2 3]] +// - 示例中的结果将会输出 2 func ExampleCloneSliceN() { var slice = []int{1, 2, 3} var result = collection.CloneSliceN(slice, 2) diff --git a/utils/generator/astgo/function.go b/utils/generator/astgo/function.go index feb9799..40bf9e7 100644 --- a/utils/generator/astgo/function.go +++ b/utils/generator/astgo/function.go @@ -56,6 +56,9 @@ type Function struct { } func (f *Function) Code() string { + if f.Test { + f.decl.Doc = nil + } var bb bytes.Buffer if err := format.Node(&bb, token.NewFileSet(), f.decl); err != nil { panic(err) diff --git a/utils/generator/genreadme/builder.go b/utils/generator/genreadme/builder.go index c2061c2..435c5ad 100644 --- a/utils/generator/genreadme/builder.go +++ b/utils/generator/genreadme/builder.go @@ -191,15 +191,34 @@ func (b *Builder) genStructs() { } b.newLine() if example := b.p.GetExampleTest(function); example != nil { - b.newLine("示例代码：", "```go\n", example.Code(), "```\n") + b.newLine("**示例代码：**").newLine() + if len(example.Comments.Clear) > 0 { + for _, s := range example.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } + b.newLine("```go\n", example.Code(), "```\n") } if unitTest := b.p.GetUnitTest(function); unitTest != nil { b.detailsStart("查看 / 收起单元测试") + if len(unitTest.Comments.Clear) > 0 { + for _, s := range unitTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", unitTest.Code(), "```\n") b.detailsEnd() } if benchmarkTest := b.p.GetBenchmarkTest(function); benchmarkTest != nil { b.detailsStart("查看 / 收起基准测试") + if len(benchmarkTest.Comments.Clear) > 0 { + for _, s := range benchmarkTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", benchmarkTest.Code(), "```\n") b.detailsEnd() } @@ -293,15 +312,34 @@ func (b *Builder) genStructs() { b.quote(comment) } if example := b.p.GetExampleTest(function); example != nil { - b.newLine("示例代码：", "```go\n", example.Code(), "```\n") + b.newLine("**示例代码：**").newLine() + if len(example.Comments.Clear) > 0 { + for _, s := range example.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } + b.newLine("```go\n", example.Code(), "```\n") } if unitTest := b.p.GetUnitTest(function); unitTest != nil { b.detailsStart("查看 / 收起单元测试") + if len(unitTest.Comments.Clear) > 0 { + for _, s := range unitTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", unitTest.Code(), "```\n") b.detailsEnd() } if benchmarkTest := b.p.GetBenchmarkTest(function); benchmarkTest != nil { b.detailsStart("查看 / 收起基准测试") + if len(benchmarkTest.Comments.Clear) > 0 { + for _, s := range benchmarkTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", benchmarkTest.Code(), "```\n") b.detailsEnd() } diff --git a/utils/geometry/README.md b/utils/geometry/README.md index 238a8bb..9dc4d81 100644 --- a/utils/geometry/README.md +++ b/utils/geometry/README.md @@ -136,7 +136,8 @@ geometry 旨在提供一组用于处理几何形状和计算几何属性的函 > 通过传入圆的半径和需要的点数量，生成一个圆 -示例代码： +**示例代码：** + ```go func ExampleNewCircle() { @@ -480,7 +481,8 @@ func TestNewPoint(t *testing.T) { > 通过传入的一组坐标 points 计算一个图形覆盖的矩形范围 -示例代码： +**示例代码：** + ```go func ExampleGetShapeCoverageAreaWithPoint() { @@ -525,7 +527,8 @@ func TestGetShapeCoverageAreaWithPoint(t *testing.T) { > 通过传入的一组坐标 positions 计算一个图形覆盖的矩形范围 -示例代码： +**示例代码：** + ```go func ExampleGetShapeCoverageAreaWithPos() { @@ -563,7 +566,8 @@ func TestGetShapeCoverageAreaWithPos(t *testing.T) { > 将一个图形覆盖矩形范围设置为无边的 > - 无边化表示会将多余的部分进行裁剪，例如图形左边从 2 开始的时候，那么左边将会被裁剪到从 0 开始 -示例代码： +**示例代码：** + ```go func ExampleCoverageAreaBoundless() { @@ -695,7 +699,8 @@ func TestGenerateShapeOnRectangle(t *testing.T) { > 通过多个点生成一个形状进行返回 -示例代码： +**示例代码：** + ```go func ExampleNewShape() { @@ -738,7 +743,8 @@ func TestNewShape(t *testing.T) { > 通过字符串将指定 rune 转换为点位置生成形状进行返回 > - 每个点的顺序从上到下，从左到右 -示例代码： +**示例代码：** + ```go func ExampleNewShapeWithString() { @@ -1012,7 +1018,8 @@ type Shape[V generic.SignedNumber] []Point[V] ``` #### func (Shape) Points() []Point[V] > 获取这个形状的所有点 -示例代码： +**示例代码：** + ```go func ExampleShape_Points() { @@ -1049,7 +1056,8 @@ func TestShape_Points(t *testing.T) { *** #### func (Shape) PointCount() int > 获取这个形状的点数量 -示例代码： +**示例代码：** + ```go func ExampleShape_PointCount() { @@ -1088,7 +1096,8 @@ func TestShape_PointCount(t *testing.T) { *** #### func (Shape) String() string > 将该形状转换为可视化的字符串进行返回 -示例代码： +**示例代码：** + ```go func ExampleShape_String() { @@ -1126,7 +1135,8 @@ func TestShape_String(t *testing.T) { > - 返回的坐标为原始形状的坐标 > > 可通过可选项对搜索结果进行过滤 -示例代码： +**示例代码：** + ```go func ExampleShape_ShapeSearch() { diff --git a/utils/geometry/astar/README.md b/utils/geometry/astar/README.md index b44daf6..63809a3 100644 --- a/utils/geometry/astar/README.md +++ b/utils/geometry/astar/README.md @@ -58,7 +58,8 @@ astar 提供用于实现 A* 算法的函数和数据结构。A* 算法是一种 > - 函数内部使用了堆数据结构来管理待处理的节点。 > - 函数返回一个节点序列，表示从起点到终点的最短路径。如果找不到路径，则返回空序列。 -示例代码： +**示例代码：** + ```go func ExampleFind() { diff --git a/utils/geometry/navmesh/README.md b/utils/geometry/navmesh/README.md index 04d006e..af138da 100644 --- a/utils/geometry/navmesh/README.md +++ b/utils/geometry/navmesh/README.md @@ -99,7 +99,8 @@ type NavMesh[V generic.SignedNumber] struct { > - 如果起点或终点不在任何形状内部，且 NavMesh 的 meshShrinkAmount 大于0，则会考虑缩小的形状。 > - 使用 A* 算法在 NavMesh 上搜索从起点形状到终点形状的最短路径。 > - 使用漏斗算法对路径进行优化，以得到最终的路径点序列。 -示例代码： +**示例代码：** + ```go func ExampleNavMesh_FindPath() { diff --git a/utils/hub/README.md b/utils/hub/README.md index 63d2ed7..e518202 100644 --- a/utils/hub/README.md +++ b/utils/hub/README.md @@ -34,7 +34,8 @@ > 创建一个 ObjectPool -示例代码： +**示例代码：** + ```go func ExampleNewObjectPool() { diff --git a/utils/leaderboard/README.md b/utils/leaderboard/README.md index 3cd06c1..d42bd9a 100644 --- a/utils/leaderboard/README.md +++ b/utils/leaderboard/README.md @@ -38,7 +38,8 @@ > 创建一个基于内存的二分查找排行榜 -示例代码： +**示例代码：** + ```go func ExampleNewBinarySearch() { diff --git a/utils/maths/README.md b/utils/maths/README.md index 0b49848..db1cf2e 100644 --- a/utils/maths/README.md +++ b/utils/maths/README.md @@ -61,7 +61,8 @@ > 检查一组值是否连续 -示例代码： +**示例代码：** + ```go func ExampleIsContinuity() { @@ -147,7 +148,8 @@ func ExampleIsContinuity() { > 将一组非连续的数字转换为从1开始的连续数字 > - 返回值是一个 map，key 是从 1 开始的连续数字，value 是原始数字 -示例代码： +**示例代码：** + ```go func ExampleToContinuous() { diff --git a/utils/moving/README.md b/utils/moving/README.md index 5f88634..61111df 100644 --- a/utils/moving/README.md +++ b/utils/moving/README.md @@ -41,7 +41,8 @@ > 创建一个用于2D对象移动的实例(TwoDimensional) -示例代码： +**示例代码：** + ```go func ExampleNewTwoDimensional() { diff --git a/utils/sorts/README.md b/utils/sorts/README.md index 29f8404..57fc082 100644 --- a/utils/sorts/README.md +++ b/utils/sorts/README.md @@ -34,7 +34,8 @@ > > 该函数在存在循环依赖的情况下将会返回 ErrCircularDependencyDetected 错误 -示例代码： +**示例代码：** + ```go func ExampleTopological() { diff --git a/utils/super/README.md b/utils/super/README.md index 8c80309..6797a26 100644 --- a/utils/super/README.md +++ b/utils/super/README.md @@ -159,7 +159,8 @@ func TestGetError(t *testing.T) { > recover 错误转换 -示例代码： +**示例代码：** + ```go func ExampleRecoverTransform() { @@ -595,7 +596,8 @@ func TestConvert(t *testing.T) { > 对特定表达式进行校验，当表达式不成立时，将执行 handle -示例代码： +**示例代码：** + ```go func ExampleVerify() { @@ -622,7 +624,8 @@ func ExampleVerify() { > 检查 version2 对于 version1 来说是不是旧版本 -示例代码： +**示例代码：** + ```go func ExampleOldVersion() { @@ -684,7 +687,8 @@ func BenchmarkOldVersion(b *testing.B) { > - 如果 version1 小于 version2，它将返回 -1 > - 如果 version1 和 version2 相等，它将返回 0 -示例代码： +**示例代码：** + ```go func ExampleCompareVersion() { diff --git a/utils/times/README.md b/utils/times/README.md index 033d92f..091682e 100644 --- a/utils/times/README.md +++ b/utils/times/README.md @@ -87,7 +87,8 @@ > 计算下一个N秒在多少秒之后 -示例代码： +**示例代码：** + ```go func ExampleCalcNextSecWithTime() {