补强注释

src/source/app/TetrisTimers.cpp

@@ -1,10 +1,16 @@
 #include "stdafx.h"
+/**
+ * @file TetrisTimers.cpp
+ * @brief 实现游戏下落、视觉特效、致谢动画和 Rogue 限时状态的定时推进。
+ */
+
 #include "TetrisAppInternal.h"
 
 static MMRESULT creditTimerHandle = 0;
 
 /**
  * @brief 多媒体定时器回调，用于高频率请求致谢页动画刷新。
+ * @param userData 创建定时器时传入的窗口句柄。
  */
 static void CALLBACK CreditTimerCallback(UINT, UINT, DWORD_PTR userData, DWORD_PTR, DWORD_PTR)
 {
@@ -17,6 +23,7 @@ static void CALLBACK CreditTimerCallback(UINT, UINT, DWORD_PTR userData, DWORD_P
 
 /**
  * @brief 重置主下落定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void ResetGameTimer(HWND hWnd)
 {
@@ -26,6 +33,7 @@ void ResetGameTimer(HWND hWnd)
 
 /**
  * @brief 启动游戏、特效和致谢页动画定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void StartAppTimers(HWND hWnd)
 {
@@ -39,12 +47,14 @@ void StartAppTimers(HWND hWnd)
         TIME_PERIODIC | TIME_CALLBACK_FUNCTION);
     if (creditTimerHandle == 0)
     {
+        // 多媒体定时器不可用时退回普通窗口定时器，保证致谢页仍可动画。
         SetTimer(hWnd, CREDIT_TIMER_ID, CREDIT_TIMER_INTERVAL, nullptr);
     }
 }
 
 /**
  * @brief 停止游戏、特效和致谢页动画定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void StopAppTimers(HWND hWnd)
 {
@@ -63,6 +73,7 @@ void StopAppTimers(HWND hWnd)
 
 /**
  * @brief 处理致谢页高频动画刷新消息。
+ * @param hWnd 当前窗口句柄。
  */
 void HandleCreditTick(HWND hWnd)
 {
@@ -74,6 +85,8 @@ void HandleCreditTick(HWND hWnd)
 
 /**
  * @brief 推进 Rogue 限时状态并按需要重置下落定时器。
+ * @param hWnd 当前窗口句柄。
+ * @return 任意状态变化需要刷新界面时返回 true。
  */
 static bool TickRogueTimedStates(HWND hWnd)
 {
@@ -121,6 +134,8 @@ static bool TickRogueTimedStates(HWND hWnd)
 
 /**
  * @brief 检查极限玩家的危险等级计时。
+ * @param hWnd 当前窗口句柄。
+ * @return 危险等级变化时返回 true。
  */
 static bool TickExtremeDanger(HWND hWnd)
 {
@@ -156,6 +171,8 @@ static bool TickExtremeDanger(HWND hWnd)
 
 /**
  * @brief 检查高堆叠触发的时间缓流。
+ * @param hWnd 当前窗口句柄。
+ * @return 成功触发时间缓流时返回 true。
  */
 static bool TryStartTimeDilation(HWND hWnd)
 {
@@ -204,6 +221,8 @@ static bool TryStartTimeDilation(HWND hWnd)
 
 /**
  * @brief 推进一次自动下落逻辑。
+ * @param hWnd 当前窗口句柄。
+ * @return 游戏状态推进后需要刷新界面返回 true。
  */
 static bool TickGameFall(HWND hWnd)
 {
@@ -248,6 +267,8 @@ static bool TickGameFall(HWND hWnd)
 
 /**
  * @brief 处理窗口定时器消息。
+ * @param hWnd 当前窗口句柄。
+ * @param timerId 触发的定时器编号。
  */
 void HandleTimerMessage(HWND hWnd, WPARAM timerId)
 {