docs: 优化泛型结构体函数的文档展示

2024-01-15 11:46:08 +08:00
parent 5ea3202732
commit 6e6f33899b
15 changed files with 1464 additions and 6 deletions
--- a/utils/aoi/README.md
+++ b/utils/aoi/README.md
@@ -83,6 +83,18 @@ type TwoDimensional[EID generic.Basic, PosType generic.SignedNumber, E TwoDimens
 	repartitionQueue []func()
 }
 ```
+#### func (*TwoDimensional) AddEntity(entity E)
+***
+#### func (*TwoDimensional) DeleteEntity(entity E)
+***
+#### func (*TwoDimensional) Refresh(entity E)
+***
+#### func (*TwoDimensional) GetFocus(id EID)  map[EID]E
+***
+#### func (*TwoDimensional) SetSize(width int, height int)
+***
+#### func (*TwoDimensional) SetAreaSize(width int, height int)
+***
 <span id="struct_TwoDimensionalEntity"></span>
 ### TwoDimensionalEntity `INTERFACE`
 基于2D定义的AOI对象功能接口
--- a/utils/arrangement/README.md
+++ b/utils/arrangement/README.md
@@ -127,6 +127,25 @@ type Area[ID comparable, AreaInfo any] struct {
 	evaluate    AreaEvaluateHandle[ID, AreaInfo]
 }
 ```
+#### func (*Area) GetAreaInfo()  AreaInfo
+> 获取编排区域的信息
+***
+#### func (*Area) GetItems()  map[ID]Item[ID]
+> 获取编排区域中的所有成员
+***
+#### func (*Area) IsAllow(item Item[ID]) (constraintErr error, conflictItems map[ID]Item[ID], allow bool)
+> 检测一个成员是否可以被添加到该编排区域中
+***
+#### func (*Area) IsConflict(item Item[ID])  bool
+> 检测一个成员是否会造成冲突
+***
+#### func (*Area) GetConflictItems(item Item[ID])  map[ID]Item[ID]
+> 获取与一个成员产生冲突的所有其他成员
+***
+#### func (*Area) GetScore(extra ...Item[ID])  float64
+> 获取该编排区域的评估分数
+>   - 当 extra 不为空时，将会将 extra 中的内容添加到 items 中进行评估
+***
 <span id="struct_AreaOption"></span>
 ### AreaOption `STRUCT`
 编排区域选项
@@ -157,6 +176,65 @@ type Arrangement[ID comparable, AreaInfo any] struct {
 	conflictHandles   []ConflictHandle[ID, AreaInfo]
 }
 ```
+#### func (*Arrangement) AddArea(areaInfo AreaInfo, options ...AreaOption[ID, AreaInfo])
+> 添加一个编排区域
+***
+#### func (*Arrangement) AddItem(item Item[ID])
+> 添加一个成员
+***
+#### func (*Arrangement) Arrange() (areas []*Area[ID, AreaInfo], noSolution map[ID]Item[ID])
+> 编排
+<details>
+<summary>查看 / 收起单元测试</summary>
+
+
+```go
+
+func TestArrangement_Arrange(t *testing.T) {
+	var a = arrangement.NewArrangement[int, *Team]()
+	a.AddArea(&Team{ID: 1}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error {
+		if len(area.GetItems()) >= 2 {
+			return errors.New("too many")
+		}
+		return nil
+	}))
+	a.AddArea(&Team{ID: 2}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error {
+		if len(area.GetItems()) >= 1 {
+			return errors.New("too many")
+		}
+		return nil
+	}))
+	a.AddArea(&Team{ID: 3}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error {
+		if len(area.GetItems()) >= 2 {
+			return errors.New("too many")
+		}
+		return nil
+	}))
+	for i := 0; i < 10; i++ {
+		a.AddItem(&Player{ID: i + 1})
+	}
+	res, no := a.Arrange()
+	for _, area := range res {
+		var str = fmt.Sprintf("area %d: ", area.GetAreaInfo().ID)
+		for id := range area.GetItems() {
+			str += fmt.Sprintf("%d ", id)
+		}
+		fmt.Println(str)
+	}
+	var noStr = "no: "
+	for _, i := range no {
+		noStr += fmt.Sprintf("%d ", i.GetID())
+	}
+	fmt.Println(noStr)
+}
+
+```
+
+
+</details>
+
+
+***
 <span id="struct_Editor"></span>
 ### Editor `STRUCT`
 提供了大量辅助函数的编辑器
@@ -169,6 +247,48 @@ type Editor[ID comparable, AreaInfo any] struct {
 	retryCount int
 }
 ```
+#### func (*Editor) GetPendingCount()  int
+> 获取待编排的成员数量
+***
+#### func (*Editor) RemoveAreaItem(area *Area[ID, AreaInfo], item Item[ID])
+> 从编排区域中移除一个成员到待编排队列中，如果该成员不存在于编排区域中，则不进行任何操作
+***
+#### func (*Editor) AddAreaItem(area *Area[ID, AreaInfo], item Item[ID])
+> 将一个成员添加到编排区域中，如果该成员已经存在于编排区域中，则不进行任何操作
+***
+#### func (*Editor) GetAreas()  []*Area[ID, AreaInfo]
+> 获取所有的编排区域
+***
+#### func (*Editor) GetAreasWithScoreAsc(extra ...Item[ID])  []*Area[ID, AreaInfo]
+> 获取所有的编排区域，并按照分数升序排序
+***
+#### func (*Editor) GetAreasWithScoreDesc(extra ...Item[ID])  []*Area[ID, AreaInfo]
+> 获取所有的编排区域，并按照分数降序排序
+***
+#### func (*Editor) GetRetryCount()  int
+> 获取重试次数
+***
+#### func (*Editor) GetThresholdProgressRate()  float64
+> 获取重试次数阈值进度
+***
+#### func (*Editor) GetAllowAreas(item Item[ID])  []*Area[ID, AreaInfo]
+> 获取允许的编排区域
+***
+#### func (*Editor) GetNoAllowAreas(item Item[ID])  []*Area[ID, AreaInfo]
+> 获取不允许的编排区域
+***
+#### func (*Editor) GetBestAllowArea(item Item[ID])  *Area[ID, AreaInfo]
+> 获取最佳的允许的编排区域，如果不存在，则返回 nil
+***
+#### func (*Editor) GetBestNoAllowArea(item Item[ID])  *Area[ID, AreaInfo]
+> 获取最佳的不允许的编排区域，如果不存在，则返回 nil
+***
+#### func (*Editor) GetWorstAllowArea(item Item[ID])  *Area[ID, AreaInfo]
+> 获取最差的允许的编排区域，如果不存在，则返回 nil
+***
+#### func (*Editor) GetWorstNoAllowArea(item Item[ID])  *Area[ID, AreaInfo]
+> 获取最差的不允许的编排区域，如果不存在，则返回 nil
+***
 <span id="struct_Item"></span>
 ### Item `INTERFACE`
 编排成员
--- a/utils/collection/mappings/README.md
+++ b/utils/collection/mappings/README.md
@@ -46,3 +46,55 @@ type SyncMap[K comparable, V any] struct {
 	atom bool
 }
 ```
+#### func (*SyncMap) Set(key K, value V)
+> 设置一个值
+***
+#### func (*SyncMap) Get(key K)  V
+> 获取一个值
+***
+#### func (*SyncMap) Atom(handle func (m map[K]V))
+> 原子操作
+***
+#### func (*SyncMap) Exist(key K)  bool
+> 判断是否存在
+***
+#### func (*SyncMap) GetExist(key K) ( V,  bool)
+> 获取一个值并判断是否存在
+***
+#### func (*SyncMap) Delete(key K)
+> 删除一个值
+***
+#### func (*SyncMap) DeleteGet(key K)  V
+> 删除一个值并返回
+***
+#### func (*SyncMap) DeleteGetExist(key K) ( V,  bool)
+> 删除一个值并返回是否存在
+***
+#### func (*SyncMap) DeleteExist(key K)  bool
+> 删除一个值并返回是否存在
+***
+#### func (*SyncMap) Clear()
+> 清空
+***
+#### func (*SyncMap) ClearHandle(handle func (key K, value V))
+> 清空并处理
+***
+#### func (*SyncMap) Range(handle func (key K, value V)  bool)
+> 遍历所有值，如果 handle 返回 true 则停止遍历
+***
+#### func (*SyncMap) Keys()  []K
+> 获取所有的键
+***
+#### func (*SyncMap) Slice()  []V
+> 获取所有的值
+***
+#### func (*SyncMap) Map()  map[K]V
+> 转换为普通 map
+***
+#### func (*SyncMap) Size()  int
+> 获取数量
+***
+#### func (*SyncMap) MarshalJSON() ( []byte,  error)
+***
+#### func (*SyncMap) UnmarshalJSON(bytes []byte)  error
+***
--- a/utils/fsm/README.md
+++ b/utils/fsm/README.md
@@ -85,6 +85,33 @@ type FSM[State comparable, Data any] struct {
 	exitAfterEventHandles   map[State][]func(state *FSM[State, Data])
 }
 ```
+#### func (*FSM) Update()
+> 触发当前状态
+***
+#### func (*FSM) Register(state State, options ...Option[State, Data])
+> 注册状态
+***
+#### func (*FSM) Unregister(state State)
+> 反注册状态
+***
+#### func (*FSM) HasState(state State)  bool
+> 检查状态机是否存在特定状态
+***
+#### func (*FSM) Change(state State)
+> 改变状态机状态到新的状态
+***
+#### func (*FSM) Current() (state State)
+> 获取当前状态
+***
+#### func (*FSM) GetData()  Data
+> 获取状态机数据
+***
+#### func (*FSM) IsZero()  bool
+> 检查状态机是否无状态
+***
+#### func (*FSM) PrevIsZero()  bool
+> 检查状态机上一个状态是否无状态
+***
 <span id="struct_Option"></span>
 ### Option `STRUCT`

--- a/utils/generator/astgo/name.go
+++ b/utils/generator/astgo/name.go
@@ -14,7 +14,8 @@ func newName(expr ast.Expr) string {
 	//case *ast.FuncType:
 	//case *ast.InterfaceType:
 	//case *ast.MapType:
-	//case *ast.ChanType:
+	case *ast.ChanType:
+		str.WriteString(newName(e.Value))
 	case *ast.Ident:
 		str.WriteString(e.Name)
 	case *ast.Ellipsis:
@@ -28,13 +29,17 @@ func newName(expr ast.Expr) string {
 	case *ast.IndexExpr:
 		str.WriteString(newName(e.X))
 	case *ast.IndexListExpr:
+		str.WriteString(newName(e.X))
 	case *ast.SliceExpr:
-	case *ast.TypeAssertExpr:
-	case *ast.CallExpr:
+		str.WriteString(newName(e.X))
+	//case *ast.TypeAssertExpr:
+	//case *ast.CallExpr:
 	case *ast.StarExpr:
 		str.WriteString(newName(e.X))
 	case *ast.UnaryExpr:
+		str.WriteString(newName(e.X))
 	case *ast.BinaryExpr:
+		str.WriteString(newName(e.X))
 	}
 	return str.String()
 }
--- a/utils/geometry/README.md
+++ b/utils/geometry/README.md
@@ -947,6 +947,8 @@ type LineSegmentCap[V generic.SignedNumber, Data any] struct {
 	Data Data
 }
 ```
+#### func (*LineSegmentCap) GetData()  Data
+***
 <span id="struct_Point"></span>
 ### Point `STRUCT`
 表示了一个由 x、y 坐标组成的点
@@ -1010,6 +1012,9 @@ type PointCap[V generic.SignedNumber, D any] struct {
 	Data D
 }
 ```
+#### func (PointCap) GetData()  D
+> 获取数据
+***
 <span id="struct_Shape"></span>
 ### Shape `STRUCT`
 通过多个点表示了一个形状
--- a/utils/leaderboard/README.md
+++ b/utils/leaderboard/README.md
@@ -76,6 +76,107 @@ type BinarySearch[CompetitorID comparable, Score generic.Ordered] struct {
 	rankClearBeforeEventHandles []BinarySearchRankClearBeforeEventHandle[CompetitorID, Score]
 }
 ```
+#### func (*BinarySearch) Competitor(competitorId CompetitorID, score Score)
+> 声明排行榜竞争者
+>   - 如果竞争者存在的情况下，会更新已有成绩，否则新增竞争者
+**示例代码：**
+
+```go
+
+func ExampleBinarySearch_Competitor() {
+	bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10))
+	scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666}
+	for i := 1; i <= 15; i++ {
+		bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1])
+	}
+	for rank, competitor := range bs.GetAllCompetitor() {
+		fmt.Println(rank, competitor)
+	}
+}
+
+```
+
+***
+#### func (*BinarySearch) RemoveCompetitor(competitorId CompetitorID)
+> 删除特定竞争者
+**示例代码：**
+
+```go
+
+func ExampleBinarySearch_RemoveCompetitor() {
+	bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10))
+	scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666}
+	for i := 1; i <= 15; i++ {
+		bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1])
+	}
+	bs.RemoveCompetitor("competitor_ 1")
+	for rank, competitor := range bs.GetAllCompetitor() {
+		fmt.Println(rank, competitor)
+	}
+}
+
+```
+
+***
+#### func (*BinarySearch) Size()  int
+> 获取竞争者数量
+***
+#### func (*BinarySearch) GetRankDefault(competitorId CompetitorID, defaultValue int)  int
+> 获取竞争者排名，如果竞争者不存在则返回默认值
+>   - 排名从 0 开始
+***
+#### func (*BinarySearch) GetRank(competitorId CompetitorID) ( int,  error)
+> 获取竞争者排名
+>   - 排名从 0 开始
+**示例代码：**
+
+```go
+
+func ExampleBinarySearch_GetRank() {
+	bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10))
+	scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666}
+	for i := 1; i <= 15; i++ {
+		bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1])
+	}
+	fmt.Println(bs.GetRank("competitor_ 1"))
+}
+
+```
+
+***
+#### func (*BinarySearch) GetCompetitor(rank int) (competitorId CompetitorID, err error)
+> 获取特定排名的竞争者
+***
+#### func (*BinarySearch) GetCompetitorWithRange(start int, end int) ( []CompetitorID,  error)
+> 获取第start名到第end名竞争者
+***
+#### func (*BinarySearch) GetScore(competitorId CompetitorID) (score Score, err error)
+> 获取竞争者成绩
+***
+#### func (*BinarySearch) GetScoreDefault(competitorId CompetitorID, defaultValue Score)  Score
+> 获取竞争者成绩，不存在时返回默认值
+***
+#### func (*BinarySearch) GetAllCompetitor()  []CompetitorID
+> 获取所有竞争者ID
+>   - 结果为名次有序的
+***
+#### func (*BinarySearch) Clear()
+> 清空排行榜
+***
+#### func (*BinarySearch) Cmp(s1 Score, s2 Score)  int
+***
+#### func (*BinarySearch) UnmarshalJSON(bytes []byte)  error
+***
+#### func (*BinarySearch) MarshalJSON() ( []byte,  error)
+***
+#### func (*BinarySearch) RegRankChangeEvent(handle BinarySearchRankChangeEventHandle[CompetitorID, Score])
+***
+#### func (*BinarySearch) OnRankChangeEvent(competitorId CompetitorID, oldRank int, newRank int, oldScore Score, newScore Score)
+***
+#### func (*BinarySearch) RegRankClearBeforeEvent(handle BinarySearchRankClearBeforeEventHandle[CompetitorID, Score])
+***
+#### func (*BinarySearch) OnRankClearBeforeEvent()
+***
 <span id="struct_BinarySearchRankChangeEventHandle"></span>
 ### BinarySearchRankChangeEventHandle `STRUCT`

--- a/utils/moving/README.md
+++ b/utils/moving/README.md
@@ -115,6 +115,124 @@ type TwoDimensional[EID generic.Basic, PosType generic.SignedNumber] struct {
 	position2DStopMoveEventHandles    []Position2DStopMoveEventHandle[EID, PosType]
 }
 ```
+#### func (*TwoDimensional) MoveTo(entity TwoDimensionalEntity[EID, PosType], x PosType, y PosType)
+> 设置对象移动到特定位置
+**示例代码：**
+
+```go
+
+func ExampleTwoDimensional_MoveTo() {
+	m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second))
+	defer func() {
+		m.Release()
+	}()
+	var wait sync.WaitGroup
+	m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) {
+		fmt.Println("done")
+		wait.Done()
+	})
+	wait.Add(1)
+	entity := NewEntity(1, 100)
+	m.MoveTo(entity, 50, 30)
+	wait.Wait()
+}
+
+```
+
+***
+#### func (*TwoDimensional) StopMove(id EID)
+> 停止特定对象的移动
+**示例代码：**
+
+```go
+
+func ExampleTwoDimensional_StopMove() {
+	m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second))
+	defer func() {
+		m.Release()
+	}()
+	var wait sync.WaitGroup
+	m.RegPosition2DChangeEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64], oldX, oldY float64) {
+		fmt.Println("move")
+	})
+	m.RegPosition2DStopMoveEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) {
+		fmt.Println("stop")
+		wait.Done()
+	})
+	m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) {
+		fmt.Println("done")
+		wait.Done()
+	})
+	wait.Add(1)
+	entity := NewEntity(1, 100)
+	m.MoveTo(entity, 50, 300)
+	m.StopMove(1)
+	wait.Wait()
+}
+
+```
+
+<details>
+<summary>查看 / 收起单元测试</summary>
+
+
+```go
+
+func TestTwoDimensional_StopMove(t *testing.T) {
+	var wait sync.WaitGroup
+	m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second))
+	defer func() {
+		m.Release()
+	}()
+	m.RegPosition2DChangeEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64], oldX, oldY float64) {
+		x, y := entity.GetPosition().GetXY()
+		fmt.Println(fmt.Sprintf("%d : %d | %f, %f > %f, %f", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli(), oldX, oldY, x, y))
+	})
+	m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) {
+		fmt.Println(fmt.Sprintf("%d : %d | destination", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli()))
+		wait.Done()
+	})
+	m.RegPosition2DStopMoveEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) {
+		fmt.Println(fmt.Sprintf("%d : %d | stop", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli()))
+		wait.Done()
+	})
+	for i := 0; i < 10; i++ {
+		wait.Add(1)
+		entity := NewEntity(int64(i)+1, float64(10+i))
+		m.MoveTo(entity, 50, 30)
+	}
+	time.Sleep(time.Second * 1)
+	for i := 0; i < 10; i++ {
+		m.StopMove(int64(i) + 1)
+	}
+	wait.Wait()
+}
+
+```
+
+
+</details>
+
+
+***
+#### func (*TwoDimensional) RegPosition2DChangeEvent(handle Position2DChangeEventHandle[EID, PosType])
+> 在对象位置改变时将执行注册的事件处理函数
+***
+#### func (*TwoDimensional) OnPosition2DChangeEvent(entity TwoDimensionalEntity[EID, PosType], oldX PosType, oldY PosType)
+***
+#### func (*TwoDimensional) RegPosition2DDestinationEvent(handle Position2DDestinationEventHandle[EID, PosType])
+> 在对象到达终点时将执行被注册的事件处理函数
+***
+#### func (*TwoDimensional) OnPosition2DDestinationEvent(entity TwoDimensionalEntity[EID, PosType])
+***
+#### func (*TwoDimensional) RegPosition2DStopMoveEvent(handle Position2DStopMoveEventHandle[EID, PosType])
+> 在对象停止移动时将执行被注册的事件处理函数
+***
+#### func (*TwoDimensional) OnPosition2DStopMoveEvent(entity TwoDimensionalEntity[EID, PosType])
+***
+#### func (*TwoDimensional) Release()
+> 释放对象移动对象所占用的资源
+***
 <span id="struct_TwoDimensionalEntity"></span>
 ### TwoDimensionalEntity `INTERFACE`
 2D移动对象接口定义
--- a/utils/super/README.md
+++ b/utils/super/README.md
@@ -940,6 +940,12 @@ type Matcher[Value any, Result any] struct {
 	d     bool
 }
 ```
+#### func (*Matcher) Case(value Value, result Result)  *Matcher[Value, Result]
+> 匹配
+***
+#### func (*Matcher) Default(value Result)  Result
+> 默认
+***
 <span id="struct_Permission"></span>
 ### Permission `STRUCT`

@@ -949,6 +955,18 @@ type Permission[Code generic.Integer, EntityID comparable] struct {
 	l           sync.RWMutex
 }
 ```
+#### func (*Permission) HasPermission(entityId EntityID, permission Code)  bool
+> 是否有权限
+***
+#### func (*Permission) AddPermission(entityId EntityID, permission ...Code)
+> 添加权限
+***
+#### func (*Permission) RemovePermission(entityId EntityID, permission ...Code)
+> 移除权限
+***
+#### func (*Permission) SetPermission(entityId EntityID, permission ...Code)
+> 设置权限
+***
 <span id="struct_StackGo"></span>
 ### StackGo `STRUCT`
 用于获取上一个协程调用的堆栈信息