补强注释

src/source/extensions/TetrisGameExtensions.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisGameExtensions.cpp
+ * @brief 实现玩家统计、视觉特效、模式切换、复活和帮助/致谢页面状态管理。
+ */
+
 #include "TetrisLogicInternal.h"
 
 int pendingLineClearEffectTicks = 0;
@@ -8,6 +13,8 @@ int pendingLineClearEffectLineCount = 0;
 
 /**
  * @brief 重置经典或 Rogue 模式使用的玩家统计数据。
+ * @param stats 需要重置的统计结构。
+ * @param useRogueRules 是否按 Rogue 模式设置初始经验需求。
  */
 void ResetPlayerStats(PlayerStats& stats, bool useRogueRules)
 {
@@ -85,6 +92,9 @@ void ResetPlayerStats(PlayerStats& stats, bool useRogueRules)
 
 /**
  * @brief 设置界面右侧显示的即时反馈标题、内容和持续时间。
+ * @param title 反馈标题。
+ * @param detail 反馈详情。
+ * @param ticks 显示持续的游戏计时次数。
  */
 void SetFeedbackMessage(const TCHAR* title, const TCHAR* detail, int ticks)
 {
@@ -125,6 +135,7 @@ void ResetVisualEffects()
 
 /**
  * @brief 推进视觉效果计时，并返回是否仍有动画需要刷新。
+ * @return 仍有动画需要刷新返回 true，否则返回 false。
  */
 bool TickVisualEffects()
 {
@@ -177,6 +188,7 @@ bool TickVisualEffects()
 
 /**
  * @brief 推进致谢页左右切换动画，并返回是否需要刷新界面。
+ * @return 需要刷新界面返回 true，否则返回 false。
  */
 bool TickCreditAnimation()
 {
@@ -191,6 +203,10 @@ bool TickCreditAnimation()
 
 /**
  * @brief 添加一段棋盘坐标系中的浮动文字效果。
+ * @param boardX 棋盘内部横坐标，使用 100 为一格的坐标系。
+ * @param boardY 棋盘内部纵坐标，使用 100 为一格的坐标系。
+ * @param text 浮动文字内容。
+ * @param color 文字颜色。
  */
 static void AddFloatingText(int boardX, int boardY, const TCHAR* text, COLORREF color)
 {
@@ -211,6 +227,12 @@ static void AddFloatingText(int boardX, int boardY, const TCHAR* text, COLORREF
 
 /**
  * @brief 添加一个棋盘坐标系中的粒子效果。
+ * @param boardX 粒子起始横坐标。
+ * @param boardY 粒子起始纵坐标。
+ * @param velocityX 横向速度。
+ * @param velocityY 纵向速度。
+ * @param size 粒子尺寸。
+ * @param color 粒子颜色。
  */
 static void AddParticle(int boardX, int boardY, int velocityX, int velocityY, int size, COLORREF color)
 {
@@ -233,6 +255,10 @@ static void AddParticle(int boardX, int boardY, int velocityX, int velocityY, in
 
 /**
  * @brief 在指定棋盘坐标周围生成一组爆裂粒子。
+ * @param boardX 爆裂中心横坐标。
+ * @param boardY 爆裂中心纵坐标。
+ * @param baseColor 主粒子颜色。
+ * @param strongBurst 是否使用更强的粒子数量和速度。
  */
 static void AddBurstParticles(int boardX, int boardY, COLORREF baseColor, bool strongBurst)
 {
@@ -296,6 +322,10 @@ static void AddBurstParticles(int boardX, int boardY, COLORREF baseColor, bool s
 
 /**
  * @brief 添加一个被清除格子的短时高亮效果。
+ * @param x 棋盘列号。
+ * @param y 棋盘行号。
+ * @param color 高亮颜色。
+ * @param strongFlash 是否使用更长的强高亮。
  */
 static void AddCellFlash(int x, int y, COLORREF color, bool strongFlash)
 {
@@ -315,6 +345,9 @@ static void AddCellFlash(int x, int y, COLORREF color, bool strongFlash)
 
 /**
  * @brief 暂存消行动画，等待升级选择结束后再播放。
+ * @param rows 被消除的行号数组。
+ * @param rowCount 行号数量。
+ * @param linesCleared 实际消除行数。
  */
 void QueueLineClearEffect(const int* rows, int rowCount, int linesCleared)
 {
@@ -358,6 +391,9 @@ void PlayPendingLineClearEffect()
 
 /**
  * @brief 触发标准消行动画和浮动文字。
+ * @param rows 被消除的行号数组。
+ * @param rowCount 行号数量。
+ * @param linesCleared 实际消除行数。
  */
 void TriggerLineClearEffect(const int* rows, int rowCount, int linesCleared)
 {
@@ -414,6 +450,9 @@ void TriggerLineClearEffect(const int* rows, int rowCount, int linesCleared)
 
 /**
  * @brief 为指定棋盘格集合触发清除粒子效果。
+ * @param cells 被清除格子数组。
+ * @param cellCount 格子数量。
+ * @param strongBurst 是否使用更强的粒子爆裂效果。
  */
 void TriggerCellClearEffect(const Point* cells, int cellCount, bool strongBurst)
 {
@@ -422,6 +461,10 @@ void TriggerCellClearEffect(const Point* cells, int cellCount, bool strongBurst)
 
 /**
  * @brief 为指定棋盘格集合触发带颜色区分的清除高亮和粒子效果。
+ * @param cells 被清除格子数组。
+ * @param cellCount 格子数量。
+ * @param flashColor 高亮颜色。
+ * @param strongBurst 是否使用更强的粒子爆裂效果。
  */
 void TriggerColoredCellClearEffect(const Point* cells, int cellCount, COLORREF flashColor, bool strongBurst)
 {
@@ -445,6 +488,10 @@ void TriggerColoredCellClearEffect(const Point* cells, int cellCount, COLORREF f
 
 /**
  * @brief 为一个受重力下落的固定方块记录纵向残影和落点粒子。
+ * @param x 棋盘列号。
+ * @param fromY 起始行号。
+ * @param toY 目标行号。
+ * @param cellValue 方块格子值。
  */
 void TriggerGravityFallEffect(int x, int fromY, int toY, int cellValue)
 {
@@ -490,6 +537,10 @@ void TriggerGravityFallEffect(int x, int fromY, int toY, int cellValue)
 
 /**
  * @brief 判断指定方块、旋转状态和位置是否可以合法放置。
+ * @param pieceType 方块类型编号。
+ * @param pieceState 方块旋转状态。
+ * @param position 待检测的左上角坐标。
+ * @return 可以放置返回 true，否则返回 false。
  */
 bool IsPiecePlacementValid(int pieceType, int pieceState, Point position)
 {
@@ -522,6 +573,9 @@ bool IsPiecePlacementValid(int pieceType, int pieceState, Point position)
 
 /**
  * @brief 尝试把旋转后的方块横向偏移指定格数后放置。
+ * @param nextState 旋转后的状态编号。
+ * @param offsetX 横向试探偏移。
+ * @return 偏移后可以放置返回 true，否则返回 false。
  */
 bool TryRotateWithOffset(int nextState, int offsetX)
 {
@@ -574,6 +628,7 @@ void ReviveAfterVideo()
 
 /**
  * @brief 按指定模式开始新游戏。
+ * @param mode 游戏模式，取值来自 GameMode。
  */
 void StartGameWithMode(int mode)
 {
@@ -632,7 +687,7 @@ void OpenRulesScreen()
 }
 
 /**
- * @brief 打开致谢界面并重置致谢页切换状态。
+ * @brief 打开 Rogue 技能演示选择页并重置帮助页状态。
  */
 void OpenSkillDemoScreen()
 {
@@ -648,6 +703,9 @@ void OpenSkillDemoScreen()
     creditAnimationDirection = 0;
 }
 
+/**
+ * @brief 打开致谢界面并重置致谢页切换状态。
+ */
 void OpenCreditScreen()
 {
     rogueDemoMode = false;
@@ -664,6 +722,7 @@ void OpenCreditScreen()
 
 /**
  * @brief 切换致谢页图片，并启动左右滑动动画。
+ * @param direction 小于 0 向前切换，大于 0 向后切换。
  */
 void ChangeCreditPage(int direction)
 {