docs: 优化 README.md 的测试用例描述

game/space/README.md

@@ -38,7 +38,8 @@ space 游戏中常见的空间设计，例如房间、地图等
 <span id="NewRoomManager"></span>
 > 创建房间管理器 RoomManager 的实例
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewRoomManager() {

server/README.md

@@ -300,7 +300,8 @@ func TestNewBot(t *testing.T) {
 <span id="New"></span>
 > 根据特定网络类型创建一个服务器
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNew() {
@@ -351,7 +352,8 @@ func TestNew(t *testing.T) {
 <span id="BindService"></span>
 > 绑定服务到特定 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() {

server/internal/dispatcher/README.md

@@ -40,7 +40,8 @@
 <span id="NewDispatcher"></span>
 > 创建一个新的消息分发器 Dispatcher 实例
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewDispatcher() {
@@ -111,7 +112,8 @@ func TestNewDispatcher(t *testing.T) {
 <span id="NewManager"></span>
 > 生成消息分发器管理器
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewManager() {

server/router/README.md

@@ -37,7 +37,8 @@
 <span id="NewMultistage"></span>
 > 创建一个支持多级分类的路由器
 
-示例代码：
+**示例代码：**
+
 ```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() {

server/writeloop/README.md

@@ -53,7 +53,8 @@
 > 
 > 传入 writeHandler 的消息对象是从 pool 中获取的，并且在 writeHandler 执行完成后会被放回 pool 中，因此 writeHandler 不应该持有消息对象的引用，同时也不应该主动释放消息对象
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewUnbounded() {

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

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)

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)

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()
 				}

utils/geometry/README.md

@@ -136,7 +136,8 @@ geometry 旨在提供一组用于处理几何形状和计算几何属性的函
 <span id="NewCircle"></span>
 > 通过传入圆的半径和需要的点数量，生成一个圆
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewCircle() {
@@ -480,7 +481,8 @@ func TestNewPoint(t *testing.T) {
 <span id="GetShapeCoverageAreaWithPoint"></span>
 > 通过传入的一组坐标 points 计算一个图形覆盖的矩形范围
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleGetShapeCoverageAreaWithPoint() {
@@ -525,7 +527,8 @@ func TestGetShapeCoverageAreaWithPoint(t *testing.T) {
 <span id="GetShapeCoverageAreaWithPos"></span>
 > 通过传入的一组坐标 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) {
 <span id="NewShape"></span>
 > 通过多个点生成一个形状进行返回
 
-示例代码：
+**示例代码：**
+
 ```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() {

utils/geometry/astar/README.md

@@ -58,7 +58,8 @@ astar 提供用于实现 A* 算法的函数和数据结构。A* 算法是一种
 >   - 函数内部使用了堆数据结构来管理待处理的节点。
 >   - 函数返回一个节点序列，表示从起点到终点的最短路径。如果找不到路径，则返回空序列。
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleFind() {

utils/geometry/navmesh/README.md

@@ -99,7 +99,8 @@ type NavMesh[V generic.SignedNumber] struct {
 >   - 如果起点或终点不在任何形状内部，且 NavMesh 的 meshShrinkAmount 大于0，则会考虑缩小的形状。
 >   - 使用 A* 算法在 NavMesh 上搜索从起点形状到终点形状的最短路径。
 >   - 使用漏斗算法对路径进行优化，以得到最终的路径点序列。
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNavMesh_FindPath() {

utils/hub/README.md

@@ -34,7 +34,8 @@
 <span id="NewObjectPool"></span>
 > 创建一个 ObjectPool
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewObjectPool() {

utils/leaderboard/README.md

@@ -38,7 +38,8 @@
 <span id="NewBinarySearch"></span>
 > 创建一个基于内存的二分查找排行榜
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewBinarySearch() {

utils/maths/README.md

@@ -61,7 +61,8 @@
 <span id="IsContinuity"></span>
 > 检查一组值是否连续
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleIsContinuity() {
@@ -147,7 +148,8 @@ func ExampleIsContinuity() {
 > 将一组非连续的数字转换为从1开始的连续数字
 >   - 返回值是一个 map，key 是从 1 开始的连续数字，value 是原始数字
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleToContinuous() {

utils/moving/README.md

@@ -41,7 +41,8 @@
 <span id="NewTwoDimensional"></span>
 > 创建一个用于2D对象移动的实例(TwoDimensional)
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleNewTwoDimensional() {

utils/sorts/README.md

@@ -34,7 +34,8 @@
 > 
 > 该函数在存在循环依赖的情况下将会返回 ErrCircularDependencyDetected 错误
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleTopological() {

utils/super/README.md

@@ -159,7 +159,8 @@ func TestGetError(t *testing.T) {
 <span id="RecoverTransform"></span>
 > recover 错误转换
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleRecoverTransform() {
@@ -595,7 +596,8 @@ func TestConvert(t *testing.T) {
 <span id="Verify"></span>
 > 对特定表达式进行校验，当表达式不成立时，将执行 handle
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleVerify() {
@@ -622,7 +624,8 @@ func ExampleVerify() {
 <span id="OldVersion"></span>
 > 检查 version2 对于 version1 来说是不是旧版本
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleOldVersion() {
@@ -684,7 +687,8 @@ func BenchmarkOldVersion(b *testing.B) {
 >   - 如果 version1 小于 version2，它将返回 -1
 >   - 如果 version1 和 version2 相等，它将返回 0
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleCompareVersion() {

utils/times/README.md

@@ -87,7 +87,8 @@
 <span id="CalcNextSecWithTime"></span>
 > 计算下一个N秒在多少秒之后
 
-示例代码：
+**示例代码：**
+
 ```go
 
 func ExampleCalcNextSecWithTime() {