补强注释

src/include/Tetris.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file Tetris.h
+ * @brief 定义俄罗斯方块项目的全局常量、结构体、枚举、全局状态和公开函数接口。
+ */
+
 #include "resource.h"
 #include "stdafx.h"
 #include <mmsystem.h>
@@ -264,60 +269,329 @@ extern bool currentPieceIsRainbow;
 extern int bricks[7][4][4][4];
 extern COLORREF BrickColor[7];
 
+/**
+ * @brief 判断当前活动方块是否还能向下移动一格。
+ * @return 可以下落返回 true，否则返回 false。
+ */
 bool CanMoveDown();
+
+/**
+ * @brief 判断当前活动方块是否还能向左移动一格。
+ * @return 可以左移返回 true，否则返回 false。
+ */
 bool CanMoveLeft();
+
+/**
+ * @brief 判断当前活动方块是否还能向右移动一格。
+ * @return 可以右移返回 true，否则返回 false。
+ */
 bool CanMoveRight();
+
+/**
+ * @brief 将当前活动方块向下移动一格。
+ */
 void MoveDown();
+
+/**
+ * @brief 将当前活动方块向左移动一格。
+ */
 void MoveLeft();
+
+/**
+ * @brief 将当前活动方块向右移动一格。
+ */
 void MoveRight();
+
+/**
+ * @brief 尝试旋转当前活动方块，Rogue 完美旋转会额外尝试左右偏移。
+ */
 void Rotate();
+
+/**
+ * @brief 将当前活动方块直接下落到预测落点。
+ */
 void DropDown();
+
+/**
+ * @brief 将当前活动方块固定到棋盘并生成下一块。
+ */
 void Fixing();
+
+/**
+ * @brief 删除指定行并让上方棋盘整体下落。
+ * @param number 要删除的棋盘行号。
+ */
 void DeleteOneLine(int number);
+
+/**
+ * @brief 扫描棋盘、删除所有满行并触发消行结算。
+ * @return 本次删除的行数。
+ */
 int DeleteLines();
+
+/**
+ * @brief 计算当前活动方块的预测落点。
+ */
 void ComputeTarget();
+
+/**
+ * @brief 重置棋盘、方块、统计和视觉状态，开始一局新游戏。
+ */
 void Restart();
+
+/**
+ * @brief 按指定模式开始新游戏。
+ * @param mode 游戏模式，取值来自 GameMode。
+ */
 void StartGameWithMode(int mode);
+
+/**
+ * @brief 返回主菜单并清理临时玩法与界面状态。
+ */
 void ReturnToMainMenu();
+
+/**
+ * @brief 复活视频播放成功后恢复游戏并清理顶部空间。
+ */
 void ReviveAfterVideo();
+
+/**
+ * @brief 从帮助页进入 Rogue 技能演示的第一项。
+ */
 void StartRogueSkillDemo();
+
+/**
+ * @brief 从帮助页进入指定 Rogue 技能演示。
+ * @param demoIndex 技能演示序号。
+ */
 void StartRogueSkillDemoAt(int demoIndex);
+
+/**
+ * @brief 重新开始当前 Rogue 技能演示场景。
+ */
 void RestartCurrentRogueSkillDemo();
+
+/**
+ * @brief 判断当前是否处于 Rogue 技能演示模式。
+ * @return 演示模式中返回 true，否则返回 false。
+ */
 bool IsRogueSkillDemoMode();
+
+/**
+ * @brief 推进 Rogue 技能演示计时。
+ * @return 演示模式正在运行返回 true，否则返回 false。
+ */
 bool TickRogueSkillDemo();
+
+/**
+ * @brief 切换到下一项 Rogue 技能演示。
+ */
 void AdvanceRogueSkillDemo();
+
+/**
+ * @brief 获取 Rogue 技能演示条目数量。
+ * @return 可选择的演示条目总数。
+ */
 int GetRogueSkillDemoCount();
+
+/**
+ * @brief 获取指定 Rogue 技能演示名称。
+ * @param demoIndex 技能演示序号。
+ * @return 名称字符串，越界时返回空字符串。
+ */
 const TCHAR* GetRogueSkillDemoName(int demoIndex);
+
+/**
+ * @brief 获取指定 Rogue 技能演示说明。
+ * @param demoIndex 技能演示序号。
+ * @return 说明字符串，越界时返回空字符串。
+ */
 const TCHAR* GetRogueSkillDemoDetail(int demoIndex);
+
+/**
+ * @brief 获取当前 Rogue 技能演示名称。
+ * @return 当前名称，非演示模式返回空字符串。
+ */
 const TCHAR* GetCurrentRogueSkillDemoName();
+
+/**
+ * @brief 设置右侧战斗日志反馈信息。
+ * @param title 反馈标题。
+ * @param detail 反馈详情。
+ * @param ticks 保持显示的游戏计时次数。
+ */
 void SetFeedbackMessage(const TCHAR* title, const TCHAR* detail, int ticks);
+
+/**
+ * @brief 打开帮助首页。
+ */
 void OpenRulesScreen();
+
+/**
+ * @brief 打开 Rogue 技能演示选择页。
+ */
 void OpenSkillDemoScreen();
+
+/**
+ * @brief 打开致谢页。
+ */
 void OpenCreditScreen();
+
+/**
+ * @brief 切换致谢页图片。
+ * @param direction 小于 0 向前切换，大于 0 向后切换。
+ */
 void ChangeCreditPage(int direction);
+
+/**
+ * @brief 打开 Rogue 升级选择界面。
+ */
 void OpenUpgradeMenu();
+
+/**
+ * @brief 确认当前升级选择并恢复游戏流程。
+ */
 void ConfirmUpgradeSelection();
+
+/**
+ * @brief 重置升级选择界面状态。
+ */
 void ResetUpgradeUiState();
+
+/**
+ * @brief 使用或解锁后处理 Hold 备用仓逻辑。
+ */
 void HoldCurrentPiece();
+
+/**
+ * @brief 使用清屏炸弹主动技能。
+ */
 void UseScreenBomb();
+
+/**
+ * @brief 使用黑洞主动技能。
+ */
 void UseBlackHole();
+
+/**
+ * @brief 使用空中换形主动技能。
+ */
 void UseAirReshape();
+
+/**
+ * @brief 重置 Rogue 待播放视觉事件。
+ */
 void ResetPendingRogueVisualEvents();
+
+/**
+ * @brief 清空所有视觉效果状态。
+ */
 void ResetVisualEffects();
+
+/**
+ * @brief 推进视觉效果动画。
+ * @return 仍有动画需要刷新返回 true，否则返回 false。
+ */
 bool TickVisualEffects();
+
+/**
+ * @brief 推进致谢页切换动画。
+ * @return 需要刷新界面返回 true，否则返回 false。
+ */
 bool TickCreditAnimation();
+
+/**
+ * @brief 触发标准消行动画。
+ * @param rows 被消除的行号数组。
+ * @param rowCount 行号数量。
+ * @param linesCleared 实际消除行数。
+ */
 void TriggerLineClearEffect(const int* rows, int rowCount, int linesCleared);
+
+/**
+ * @brief 播放之前因升级界面暂存的消行动画。
+ */
 void PlayPendingLineClearEffect();
+
+/**
+ * @brief 触发指定棋盘格的默认清除特效。
+ * @param cells 被清除格子数组。
+ * @param cellCount 格子数量。
+ * @param strongBurst 是否使用更强的爆裂粒子。
+ */
 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);
+
+/**
+ * @brief 记录一个固定方块受重力下落的轨迹。
+ * @param x 棋盘列号。
+ * @param fromY 下落起始行号。
+ * @param toY 下落目标行号。
+ * @param cellValue 方块格子数值。
+ */
 void TriggerGravityFallEffect(int x, int fromY, int toY, int cellValue);
+
+/**
+ * @brief 为 Rogue 主动或特殊技能清除格子发放奖励。
+ * @param clearedCells 清除格子数。
+ * @param scoreGain 返回本次得分增量。
+ * @param expGain 返回本次经验增量。
+ * @param allowLevelProgress 是否允许本次奖励触发升级流程。
+ */
 void AwardRogueSkillClearRewards(int clearedCells, int& scoreGain, int& expGain, bool allowLevelProgress);
+
+/**
+ * @brief 检查 Rogue 经验是否达到升级条件。
+ */
 void CheckRogueLevelProgress();
+
+/**
+ * @brief 对棋盘固定方块应用重力下落。
+ */
 void ApplyBoardGravity();
+
+/**
+ * @brief 计算当前 Rogue 模式下落间隔。
+ * @return 下落计时器间隔，单位毫秒。
+ */
 int GetRogueFallInterval();
+
+/**
+ * @brief 获取 Rogue 当前可操作棋盘高度。
+ * @return 未被底部封锁占用的行数。
+ */
 int GetRoguePlayableHeight();
+
+/**
+ * @brief 获取 Rogue 难度系统当前封锁的底部行数。
+ * @return 封锁行数。
+ */
 int GetRogueLockedRows();
+
+/**
+ * @brief 按经过时间推进 Rogue 难度。
+ * @param elapsedMs 本次推进的时间，单位毫秒。
+ */
 void AdvanceRogueDifficulty(int elapsedMs);
+
+/**
+ * @brief 获取进化强化的合成路线文本。
+ * @param upgradeId 强化编号。
+ * @return 路线文本；普通强化返回空或空指针。
+ */
 const TCHAR* GetUpgradeSynthesisPath(int upgradeId);
 
+/**
+ * @brief 绘制当前窗口中的完整游戏界面。
+ * @param hdc 目标绘图设备上下文。
+ * @param hWnd 当前窗口句柄，用于读取客户区大小。
+ */
 void TDrawScreen(HDC hdc, HWND hWnd);

src/include/TetrisAppInternal.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file TetrisAppInternal.h
+ * @brief 声明窗口布局、输入、计时器和媒体播放等应用层内部接口。
+ */
+
 #include "Tetris.h"
 
 constexpr int GAME_TIMER_ID = 1;
@@ -22,106 +27,157 @@ struct LayoutMetrics
 
 /**
  * @brief 根据当前窗口大小计算整体界面缩放与偏移。
+ * @param hWnd 当前窗口句柄。
+ * @return 布局缩放、偏移和网格尺寸。
  */
 LayoutMetrics GetLayoutMetrics(HWND hWnd);
 
 /**
  * @brief 按当前布局比例缩放一个尺寸值。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿尺寸值。
+ * @return 缩放后的像素尺寸。
  */
 int ScaleValue(const LayoutMetrics& metrics, int value);
 
 /**
  * @brief 按当前布局比例缩放横坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿横坐标。
+ * @return 实际窗口横坐标。
  */
 int ScaleXValue(const LayoutMetrics& metrics, int value);
 
 /**
  * @brief 按当前布局比例缩放纵坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿纵坐标。
+ * @return 实际窗口纵坐标。
  */
 int ScaleYValue(const LayoutMetrics& metrics, int value);
 
 /**
  * @brief 获取主菜单选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 菜单选项序号。
+ * @return 选项在窗口中的矩形区域。
  */
 RECT GetMenuOptionRect(HWND hWnd, int index);
 
 /**
  * @brief 获取帮助页选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 帮助首页选项序号。
+ * @return 选项在窗口中的矩形区域。
  */
 RECT GetHelpOptionRect(HWND hWnd, int index);
 
 /**
  * @brief 获取技能演示列表项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 技能演示条目序号。
+ * @return 条目在窗口中的矩形区域。
  */
 RECT GetHelpSkillDemoItemRect(HWND hWnd, int index);
 
 /**
  * @brief 获取帮助页底部返回提示的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回提示在窗口中的矩形区域。
  */
 RECT GetHelpBackHintRect(HWND hWnd);
 
 /**
  * @brief 获取致谢页左右切换按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param direction 小于 0 表示左箭头，大于 0 表示右箭头。
+ * @return 切换按钮在窗口中的矩形区域。
  */
 RECT GetCreditArrowRect(HWND hWnd, int direction);
 
 /**
  * @brief 获取升级选择卡片的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 强化卡片序号。
+ * @return 卡片在窗口中的矩形区域。
  */
 RECT GetUpgradeCardRect(HWND hWnd, int index);
 
 /**
  * @brief 获取暂停或结束覆盖层按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 按钮序号。
+ * @param buttonCount 覆盖层当前按钮总数。
+ * @return 按钮在窗口中的矩形区域。
  */
 RECT GetOverlayButtonRect(HWND hWnd, int index, int buttonCount);
 
 /**
  * @brief 获取左上角返回按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回按钮在窗口中的矩形区域。
  */
 RECT GetBackButtonRect(HWND hWnd);
 
 /**
  * @brief 获取右下角音乐按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 音乐按钮在窗口中的矩形区域。
  */
 RECT GetMusicButtonRect(HWND hWnd);
 
 /**
  * @brief 判断点坐标是否落在矩形内部。
+ * @param rect 待判断矩形。
+ * @param x 点的横坐标。
+ * @param y 点的纵坐标。
+ * @return 点在矩形内返回 true，否则返回 false。
  */
 bool IsPointInRect(const RECT& rect, int x, int y);
 
 /**
  * @brief 将滚动偏移按步长调整并限制在有效范围内。
+ * @param scrollOffset 需要修改的滚动偏移。
+ * @param delta 本次滚动增量。
  */
 void AdjustScrollOffset(int& scrollOffset, int delta);
 
 /**
  * @brief 获取适配当前窗口缩放的一次滚动步长。
+ * @param hWnd 当前窗口句柄。
+ * @param baseStep 设计稿中的基础滚动步长。
+ * @return 缩放后的滚动步长。
  */
 int GetScrollStep(HWND hWnd, int baseStep);
 
 /**
  * @brief 重置主下落定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void ResetGameTimer(HWND hWnd);
 
 /**
  * @brief 启动游戏、特效和致谢页动画定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void StartAppTimers(HWND hWnd);
 
 /**
  * @brief 停止游戏、特效和致谢页动画定时器。
+ * @param hWnd 当前窗口句柄。
  */
 void StopAppTimers(HWND hWnd);
 
 /**
  * @brief 处理致谢页高频动画刷新消息。
+ * @param hWnd 当前窗口句柄。
  */
 void HandleCreditTick(HWND hWnd);
 
 /**
  * @brief 处理窗口定时器消息。
+ * @param hWnd 当前窗口句柄。
+ * @param timerId 触发的定时器编号。
  */
 void HandleTimerMessage(HWND hWnd, WPARAM timerId);
 
@@ -137,25 +193,35 @@ void StopBackgroundMusic();
 
 /**
  * @brief 切换背景音乐开关并刷新窗口。
+ * @param hWnd 当前窗口句柄。
  */
 void ToggleBackgroundMusic(HWND hWnd);
 
 /**
  * @brief 播放复活视频，播放成功返回 true。
+ * @param hWnd 当前窗口句柄，用于 MCI 播放和父窗口绑定。
+ * @return 播放成功返回 true，否则返回 false。
  */
 bool PlayReviveVideo(HWND hWnd);
 
 /**
  * @brief 处理鼠标左键释放事件，返回是否已处理。
+ * @param hWnd 当前窗口句柄。
+ * @param lParam 鼠标消息坐标参数。
+ * @return 事件已被界面逻辑消费返回 true，否则返回 false。
  */
 bool HandleMouseClick(HWND hWnd, LPARAM lParam);
 
 /**
  * @brief 处理鼠标滚轮事件。
+ * @param hWnd 当前窗口句柄。
+ * @param wParam 鼠标滚轮消息参数。
  */
 void HandleMouseWheel(HWND hWnd, WPARAM wParam);
 
 /**
  * @brief 处理键盘按键事件。
+ * @param hWnd 当前窗口句柄。
+ * @param wParam 按键虚拟键码。
  */
 void HandleKeyDown(HWND hWnd, WPARAM wParam);

src/include/TetrisAssets.h

@@ -1,19 +1,30 @@
 #pragma once
 
+/**
+ * @file TetrisAssets.h
+ * @brief 声明资源路径拼接和文件存在性检查工具函数。
+ */
+
 #include "stdafx.h"
 #include <string>
 
 /**
  * @brief 根据程序所在目录拼出项目资源文件的绝对路径。
+ * @param relativePath 相对于项目根目录的资源路径。
+ * @return 规范化后的绝对路径；解析失败时返回拼接路径。
  */
 std::wstring BuildAssetPath(const wchar_t* relativePath);
 
 /**
  * @brief 根据当前工作目录拼出项目资源文件的绝对路径。
+ * @param relativePath 相对于当前工作目录的资源路径。
+ * @return 规范化后的绝对路径；解析失败时返回拼接路径。
  */
 std::wstring BuildWorkingDirAssetPath(const wchar_t* relativePath);
 
 /**
  * @brief 判断指定路径是否存在且不是目录。
+ * @param path 待检查的文件路径。
+ * @return 文件存在且不是目录返回 true，否则返回 false。
  */
 bool FileExists(const std::wstring& path);

src/include/TetrisLogicInternal.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file TetrisLogicInternal.h
+ * @brief 声明棋盘逻辑、Rogue 结算和特殊方块效果使用的内部接口。
+ */
+
 #include "Tetris.h"
 
 extern Point pendingChainBombCenter;
@@ -11,86 +16,129 @@ extern int pendingLineClearEffectLineCount;
 
 /**
  * @brief 计算指定方块在棋盘顶部的统一生成位置。
+ * @param brickType 方块类型编号。
+ * @return 生成坐标，可能位于可视区域上方。
  */
 Point GetSpawnPoint(int brickType);
 
 /**
  * @brief 重置经典或 Rogue 模式使用的玩家统计数据。
+ * @param stats 需要重置的统计结构。
+ * @param useRogueRules 是否按 Rogue 模式设置初始经验需求。
  */
 void ResetPlayerStats(PlayerStats& stats, bool useRogueRules);
 
 /**
  * @brief 设置界面右侧显示的即时反馈标题、内容和持续时间。
+ * @param title 反馈标题。
+ * @param detail 反馈详情。
+ * @param ticks 显示持续的游戏计时次数。
  */
 void SetFeedbackMessage(const TCHAR* title, const TCHAR* detail, int ticks);
 
 /**
  * @brief 判断指定方块、旋转状态和位置是否可以合法放置。
+ * @param pieceType 方块类型编号。
+ * @param pieceState 方块旋转状态。
+ * @param position 待检测的左上角坐标。
+ * @return 可以放置返回 true，否则返回 false。
  */
 bool IsPiecePlacementValid(int pieceType, int pieceState, Point position);
 
 /**
  * @brief 判断棋盘格是否为彩虹特殊方块。
+ * @param cellValue 棋盘格存储值。
+ * @return 彩虹方块返回 true，否则返回 false。
  */
 bool IsRainbowBoardCell(int cellValue);
 
 /**
  * @brief 触发小型黑洞并返回被清除的固定方块数量。
+ * @param maxCellsToClear 最多清除的格子数。
+ * @return 实际清除格子数。
  */
 int TriggerMiniBlackHole(int maxCellsToClear);
 
 /**
  * @brief 触发彩虹方块行清除与覆盖行染色效果。
+ * @param anchorRow 作为主色判断的中心行。
+ * @param minRow 允许染色范围的最小行。
+ * @param maxRow 允许染色范围的最大行。
+ * @param recoloredCount 返回被染色的格子数。
+ * @return 被清除的主色格子数。
  */
 int TriggerRainbowColorShift(int anchorRow, int minRow, int maxRow, int& recoloredCount);
 
 /**
  * @brief 引爆清屏炸弹并返回清除格数。
+ * @return 实际清除格子数。
  */
 int TriggerScreenBomb();
 
 /**
  * @brief 清除指定中心点周围的爆破范围并返回清除格数。
+ * @param centerY 爆破中心行。
+ * @param centerX 爆破中心列。
+ * @return 实际清除格子数。
  */
 int ClearExplosiveAreaAt(int centerY, int centerX);
 
 /**
  * @brief 清除指定列并返回清除格数。
+ * @param column 目标列号。
+ * @return 实际清除格子数。
  */
 int ClearColumnAt(int column);
 
 /**
  * @brief 使用指定颜色特效清除指定列并返回清除格数。
+ * @param column 目标列号。
+ * @param flashColor 清除高亮颜色。
+ * @return 实际清除格子数。
  */
 int ClearColumnAtWithColor(int column, COLORREF flashColor);
 
 /**
  * @brief 清除指定行并返回清除格数。
+ * @param row 目标行号。
+ * @return 实际清除格子数。
  */
 int ClearRowAt(int row);
 
 /**
  * @brief 尝试填补局部空洞以稳定棋盘结构。
+ * @return 实际填补格子数。
  */
 int TryStabilizeBoard();
 
 /**
  * @brief 为当前方块刷新 Rogue 特殊方块标记。
+ * @param allowRandomSpecials 是否允许按强化概率随机生成特殊方块。
  */
 void RollCurrentPieceSpecialFlags(bool allowRandomSpecials);
 
 /**
  * @brief 暂存消行动画，等待升级选择结束后再播放。
+ * @param rows 被消除的行号数组。
+ * @param rowCount 行号数量。
+ * @param linesCleared 实际消除行数。
  */
 void QueueLineClearEffect(const int* rows, int rowCount, int linesCleared);
 
 /**
  * @brief 记录固定方块受重力下落的轨迹，用于播放纵向残影特效。
+ * @param x 棋盘列号。
+ * @param fromY 起始行号。
+ * @param toY 目标行号。
+ * @param cellValue 方块格子值。
  */
 void TriggerGravityFallEffect(int x, int fromY, int toY, int cellValue);
 
 /**
  * @brief 尝试把旋转后的方块横向偏移指定格数后放置。
+ * @param nextState 旋转后的状态编号。
+ * @param offsetX 横向试探偏移。
+ * @return 偏移后可以放置返回 true，否则返回 false。
  */
 bool TryRotateWithOffset(int nextState, int offsetX);
 
@@ -101,20 +149,29 @@ void ResetNextQueue();
 
 /**
  * @brief 消费队首下一方块并补充新的预览方块。
+ * @return 新的当前方块类型编号。
  */
 int ConsumeNextType();
 
 /**
  * @brief 结算一次标准消行带来的 Rogue 玩法效果。
+ * @param linesCleared 本次标准消行数量。
  */
 void ApplyLineClearResult(int linesCleared);
 
 /**
  * @brief 结算彩虹方块固定后的染色和清除效果。
+ * @param overflowTop 固定时是否已经越过顶部。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
  */
 void ApplyRainbowLandingEffect(bool overflowTop, const Point* fixedCells, int fixedCellCount);
 
 /**
  * @brief 结算爆破、激光、十字和稳定结构等特殊落地效果。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
+ * @param explosiveCells 爆破方块写入棋盘的格子数组。
+ * @param explosiveCellCount 爆破格子数量。
  */
 void ApplySpecialLandingEffects(const Point* fixedCells, int fixedCellCount, const Point* explosiveCells, int explosiveCellCount);

src/include/TetrisRenderInternal.h

@@ -1,15 +1,23 @@
 #pragma once
 
+/**
+ * @file TetrisRenderInternal.h
+ * @brief 声明渲染模块内部使用的 GDI+ 图片加载接口。
+ */
+
 #include "Tetris.h"
 #include <objidl.h>
 #include <gdiplus.h>
 
 /**
  * @brief 加载并缓存主背景图片。
+ * @return 成功时返回缓存位图指针，失败时返回 nullptr。
  */
 Gdiplus::Bitmap* LoadBackgroundImage();
 
 /**
  * @brief 按序号加载并缓存致谢页图片。
+ * @param index 致谢页图片序号。
+ * @return 成功时返回缓存位图指针，失败或越界时返回 nullptr。
  */
 Gdiplus::Bitmap* LoadCreditImage(int index);

src/include/resource.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file resource.h
+ * @brief 定义菜单、图标、对话框和命令等 Windows 资源编号。
+ */
+
 //{{NO_DEPENDENCIES}}
 // Microsoft Visual C++ 生成的包含文件。
 // 供 Tetris.rc 使用

src/include/stdafx.h

@@ -1,7 +1,7 @@
-// stdafx.h : 标准系统包含文件的包含文件，
-// 或是经常使用但不常更改的
-// 特定于项目的包含文件
-//
+/**
+ * @file stdafx.h
+ * @brief 集中包含 Windows、C 运行时和项目常用基础头文件。
+ */
 
 #pragma once
 

src/include/targetver.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file targetver.h
+ * @brief 设置 Windows SDK 目标平台版本，供 Win32 头文件选择可用 API。
+ */
+
 // 包括 SDKDDKVer.h 将定义可用的最高版本的 Windows 平台。
 
 // 如果要为以前的 Windows 平台生成应用程序，请包括 WinSDKVer.h，并将

src/source/Tetris.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file Tetris.cpp
+ * @brief 实现 Win32 程序入口、主窗口创建、消息分发和双缓冲绘制流程。
+ */
+
 #include "Tetris.h"
 #include "TetrisAppInternal.h"
 
@@ -10,11 +15,52 @@ TCHAR szWindowClass[MAX_LOADSTRING];
 bool bgmEnabled = true;
 
 
+/**
+ * @brief 注册主窗口类，供 CreateWindow 创建游戏窗口使用。
+ * @param hInstance 当前程序实例句柄。
+ * @return RegisterClassEx 返回的窗口类原子值。
+ */
 ATOM MyRegisterClass(HINSTANCE hInstance);
-BOOL InitInstance(HINSTANCE, int);
-LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM);
-INT_PTR CALLBACK About(HWND, UINT, WPARAM, LPARAM);
 
+/**
+ * @brief 创建、显示并更新主窗口。
+ * @param hInstance 当前程序实例句柄。
+ * @param nCmdShow 窗口初始显示方式。
+ * @return 创建成功返回 TRUE，否则返回 FALSE。
+ */
+BOOL InitInstance(HINSTANCE hInstance, int nCmdShow);
+
+/**
+ * @brief 主窗口消息回调，分发绘制、输入、计时器和生命周期消息。
+ * @param hWnd 当前窗口句柄。
+ * @param message Windows 消息编号。
+ * @param wParam 消息附加参数。
+ * @param lParam 消息附加参数。
+ * @return 消息处理结果。
+ */
+LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);
+
+/**
+ * @brief 关于对话框消息回调。
+ * @param hDlg 对话框窗口句柄。
+ * @param message Windows 消息编号。
+ * @param wParam 消息附加参数。
+ * @param lParam 消息附加参数。
+ * @return 已处理消息返回 TRUE，否则返回 FALSE。
+ */
+INT_PTR CALLBACK About(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam);
+
+/**
+ * @brief Windows 程序入口，完成窗口注册、创建和主消息循环。
+ *
+ * 函数启动时会设置 DPI 感知，加载窗口标题和类名资源，然后进入标准消息循环。
+ *
+ * @param hInstance 当前程序实例句柄。
+ * @param hPrevInstance 旧版 Windows 保留参数，本程序不使用。
+ * @param lpCmdLine 命令行字符串，本程序不使用。
+ * @param nCmdShow 窗口初始显示方式。
+ * @return 程序退出码。
+ */
 int APIENTRY _tWinMain(HINSTANCE hInstance,
     HINSTANCE hPrevInstance,
     LPTSTR lpCmdLine,
@@ -23,6 +69,7 @@ int APIENTRY _tWinMain(HINSTANCE hInstance,
     UNREFERENCED_PARAMETER(hPrevInstance);
     UNREFERENCED_PARAMETER(lpCmdLine);
 
+    // 旧版工程模板没有自动声明 DPI 感知，这里动态获取函数避免系统不支持时报错。
     HMODULE user32Module = GetModuleHandle(_T("user32.dll"));
     if (user32Module != nullptr)
     {
@@ -49,6 +96,7 @@ int APIENTRY _tWinMain(HINSTANCE hInstance,
     HACCEL hAccelTable = LoadAccelerators(hInstance, MAKEINTRESOURCE(IDC_TETRIS));
     MSG msg;
 
+    // 标准消息循环负责把键盘、鼠标、计时器和绘制消息送入窗口过程。
     while (GetMessage(&msg, nullptr, 0, 0))
     {
         if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg))
@@ -61,6 +109,11 @@ int APIENTRY _tWinMain(HINSTANCE hInstance,
     return (int)msg.wParam;
 }
 
+/**
+ * @brief 注册主窗口类，供 CreateWindow 创建游戏窗口使用。
+ * @param hInstance 当前程序实例句柄。
+ * @return RegisterClassEx 返回的窗口类原子值。
+ */
 ATOM MyRegisterClass(HINSTANCE hInstance)
 {
     WNDCLASSEX wcex;
@@ -81,6 +134,12 @@ ATOM MyRegisterClass(HINSTANCE hInstance)
     return RegisterClassEx(&wcex);
 }
 
+/**
+ * @brief 创建、显示并更新主窗口。
+ * @param hInstance 当前程序实例句柄。
+ * @param nCmdShow 窗口初始显示方式。
+ * @return 创建成功返回 TRUE，否则返回 FALSE。
+ */
 BOOL InitInstance(HINSTANCE hInstance, int nCmdShow)
 {
     RECT rect = { 0, 0, WINDOW_CLIENT_WIDTH, WINDOW_CLIENT_HEIGHT };
@@ -112,11 +171,20 @@ BOOL InitInstance(HINSTANCE hInstance, int nCmdShow)
     return TRUE;
 }
 
+/**
+ * @brief 主窗口消息回调，分发绘制、输入、计时器和生命周期消息。
+ * @param hWnd 当前窗口句柄。
+ * @param message Windows 消息编号。
+ * @param wParam 消息附加参数。
+ * @param lParam 消息附加参数。
+ * @return 消息处理结果。
+ */
 LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
 {
     switch (message)
     {
     case WM_CREATE:
+        // 创建阶段统一启动随机数、音乐和定时器，保证进入菜单时界面已经可刷新。
         timeBeginPeriod(1);
         srand((unsigned int)time(nullptr));
         ReturnToMainMenu();
@@ -170,6 +238,7 @@ LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
         return 1;
     case WM_PAINT:
     {
+        // 使用内存 DC 双缓冲绘制，减少窗口缩放和动画刷新时的闪烁。
         PAINTSTRUCT ps;
         HDC hdc = BeginPaint(hWnd, &ps);
         RECT clientRect;
@@ -199,6 +268,7 @@ LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
     }
     break;
     case WM_DESTROY:
+        // 退出前释放定时器和音频设备，避免 MCI 或多媒体定时器残留。
         StopAppTimers(hWnd);
         StopBackgroundMusic();
         timeEndPeriod(1);
@@ -211,6 +281,14 @@ LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
     return 0;
 }
 
+/**
+ * @brief 关于对话框消息回调。
+ * @param hDlg 对话框窗口句柄。
+ * @param message Windows 消息编号。
+ * @param wParam 消息附加参数。
+ * @param lParam 消息附加参数。
+ * @return 已处理消息返回 TRUE，否则返回 FALSE。
+ */
 INT_PTR CALLBACK About(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)
 {
     UNREFERENCED_PARAMETER(lParam);

src/source/TetrisLogic.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisLogic.cpp
+ * @brief 实现基础俄罗斯方块的移动、旋转、固定、消行、落点计算和重开逻辑。
+ */
+
 #include "Tetris.h"
 #include "TetrisLogicInternal.h"
 
@@ -332,7 +337,7 @@ void MoveRight()
  *
  * 游戏中的每种方块都预置了 4 种旋转状态，该函数会先尝试切换到下一状态，
  * 然后检查旋转后的方块是否越界或与固定方块重叠。
- * 如果旋转后的状态非法，则恢复到旋转前的状态。
+ * 如果旋转后的状态非法，Rogue 的完美旋转会继续尝试左右各偏移一格。
  */
 void Rotate()
 {
@@ -522,6 +527,8 @@ void DeleteOneLine(int number)
  * 如果某一行全部非 0，则调用 DeleteOneLine 删除该行，
  * 并将该行上方的内容整体下移。为了避免连续满行被漏检，
  * 删除后会继续检查当前行号。每成功消除 1 行，当前得分增加 100 分。
+ *
+ * @return 本次实际消除的行数。
  */
 int DeleteLines()
 {
@@ -557,6 +564,7 @@ int DeleteLines()
         }
     }
 
+    // 消行数量先进入玩法结算，再根据是否正在升级决定动画立即播放还是暂存。
     ApplyLineClearResult(clearedLines);
     if (currentScreen == SCREEN_UPGRADE)
     {
@@ -567,6 +575,7 @@ int DeleteLines()
         TriggerLineClearEffect(clearedRows, clearedRowCount, clearedLines);
     }
 
+    // 连环炸弹的追加爆破只在爆破方块导致后续消行时触发一次。
     if (pendingChainBombFollowup && clearedLines > 0)
     {
         pendingChainBombFollowup = false;

src/source/TetrisRender.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisRender.cpp
+ * @brief 实现主菜单、帮助页、游戏棋盘、侧栏、覆盖层和升级界面的完整绘制逻辑。
+ */
+
 #include "Tetris.h"
 #include "TetrisRenderInternal.h"
 #include <objidl.h>
@@ -8,6 +13,11 @@
 
 using namespace Gdiplus;
 
+/**
+ * @brief 按颜色缓存粒子画刷，减少动画绘制时重复创建 GDI 对象。
+ * @param color 画刷颜色。
+ * @return 可复用的实心画刷句柄；缓存满时返回临时新建画刷。
+ */
 static HBRUSH GetCachedParticleBrush(COLORREF color)
 {
     static COLORREF cachedColors[16] = {};
@@ -34,11 +44,22 @@ static HBRUSH GetCachedParticleBrush(COLORREF color)
     return CreateSolidBrush(color);
 }
 
+/**
+ * @brief 绘制当前游戏窗口的完整界面。
+ *
+ * 函数按当前屏幕状态绘制主菜单、帮助页、游戏棋盘、侧栏、覆盖层和升级选择。
+ * 由于大量绘图辅助逻辑共享当前缩放、字体和颜色，保持在同一函数内集中管理，
+ * 避免拆分时改变 GDI 对象的选择和释放顺序。
+ *
+ * @param hdc 目标绘图设备上下文。
+ * @param hWnd 当前窗口句柄，用于读取客户区大小。
+ */
 void TDrawScreen(HDC hdc, HWND hWnd)
 {
     RECT clientRect;
     GetClientRect(hWnd, &clientRect);
 
+    // 根据窗口大小计算统一缩放比例，所有坐标都从设计稿尺寸映射到实际窗口。
     int clientWidth = clientRect.right - clientRect.left;
     int clientHeight = clientRect.bottom - clientRect.top;
     int scaleX = MulDiv(clientWidth, 1000, WINDOW_CLIENT_WIDTH);
@@ -119,6 +140,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
     const BYTE panelNestedAlpha = 128;
     const BYTE panelStrongAlpha = 168;
 
+    // 背景图片存在时优先绘制图片并叠加浅色遮罩，否则使用纯色和装饰形状。
     Bitmap* backgroundImage = LoadBackgroundImage();
     if (backgroundImage != nullptr)
     {
@@ -155,6 +177,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         DeleteObject(blobBrushB);
     }
 
+    // 本函数集中创建字体，所有提前 return 分支都要在返回前释放这些 GDI 对象。
     HFONT titleFont = CreateFont(
         -SS(36), 0, 0, 0, FW_BOLD, FALSE, FALSE, FALSE,
         DEFAULT_CHARSET, OUT_OUTLINE_PRECIS, CLIP_DEFAULT_PRECIS, CLEARTYPE_NATURAL_QUALITY,
@@ -178,6 +201,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
     SetBkMode(hdc, TRANSPARENT);
     SetTextColor(hdc, textColor);
 
+    // 以下局部绘图函数共享 hdc、缩放函数和颜色，避免每个小控件重复计算上下文。
     auto DrawPanelCard = [&](const RECT& rect, COLORREF fillColor, COLORREF borderColor, int radius)
     {
         HBRUSH cardBrush = CreateSolidBrush(fillColor);
@@ -312,6 +336,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         DeleteObject(backPen);
     };
 
+    // 主菜单独立绘制并提前返回，避免后续游戏棋盘和侧栏在菜单后面继续绘制。
     if (currentScreen == SCREEN_MENU)
     {
         RECT menuCard =
@@ -439,6 +464,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         return;
     }
 
+    // 帮助、规则、图鉴、致谢和技能演示入口共用规则页卡片框架。
     if (currentScreen == SCREEN_RULES)
     {
         RECT rulesCard =
@@ -2300,6 +2326,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
             DT_LEFT | DT_TOP | DT_WORDBREAK);
     }
 
+    // 暂停和结束覆盖层只盖住棋盘区域，让两侧战斗信息仍然可见。
     if (suspendFlag || gameOverFlag)
     {
         RECT overlayRect =
@@ -2427,6 +2454,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         }
     }
 
+    // 升级选择界面在当前战局上方绘制半透明遮罩，保留背景局势作为上下文。
     if (currentScreen == SCREEN_UPGRADE)
     {
         RECT dimRect =

src/source/app/TetrisInput.cpp

@@ -1,8 +1,14 @@
 #include "stdafx.h"
+/**
+ * @file TetrisInput.cpp
+ * @brief 实现鼠标和键盘输入处理，负责菜单、帮助、升级界面和游戏操作分发。
+ */
+
 #include "TetrisAppInternal.h"
 
 /**
  * @brief 打开当前菜单选中的页面或开始对应模式。
+ * @param hWnd 当前窗口句柄，用于重置计时器和触发重绘。
  */
 static void ActivateMenuSelection(HWND hWnd)
 {
@@ -28,6 +34,7 @@ static void ActivateMenuSelection(HWND hWnd)
 
 /**
  * @brief 处理返回按钮的统一点击行为。
+ * @param hWnd 当前窗口句柄，用于触发重绘。
  */
 static void HandleBackButtonClick(HWND hWnd)
 {
@@ -50,6 +57,10 @@ static void HandleBackButtonClick(HWND hWnd)
 
 /**
  * @brief 处理主菜单点击。
+ * @param hWnd 当前窗口句柄。
+ * @param mouseX 鼠标横坐标。
+ * @param mouseY 鼠标纵坐标。
+ * @return 当前界面是菜单时返回 true，否则返回 false。
  */
 static bool HandleMenuClick(HWND hWnd, int mouseX, int mouseY)
 {
@@ -75,6 +86,10 @@ static bool HandleMenuClick(HWND hWnd, int mouseX, int mouseY)
 
 /**
  * @brief 处理规则、帮助、致谢和技能演示页点击。
+ * @param hWnd 当前窗口句柄。
+ * @param mouseX 鼠标横坐标。
+ * @param mouseY 鼠标纵坐标。
+ * @return 当前界面是帮助页时返回 true，否则返回 false。
  */
 static bool HandleRulesClick(HWND hWnd, int mouseX, int mouseY)
 {
@@ -85,6 +100,7 @@ static bool HandleRulesClick(HWND hWnd, int mouseX, int mouseY)
 
     if (helpState.currentPage == 0)
     {
+        // 帮助首页的四个入口分别进入介绍、操作、图鉴和技能演示页。
         for (int i = 0; i < helpState.optionCount; i++)
         {
             if (IsPointInRect(GetHelpOptionRect(hWnd, i), mouseX, mouseY))
@@ -124,6 +140,7 @@ static bool HandleRulesClick(HWND hWnd, int mouseX, int mouseY)
             return true;
         }
 
+        // 技能演示页的列表项直接启动对应预设棋盘。
         int demoCount = GetRogueSkillDemoCount();
         for (int i = 0; i < demoCount; i++)
         {
@@ -162,6 +179,10 @@ static bool HandleRulesClick(HWND hWnd, int mouseX, int mouseY)
 
 /**
  * @brief 处理升级选择界面点击。
+ * @param hWnd 当前窗口句柄。
+ * @param mouseX 鼠标横坐标。
+ * @param mouseY 鼠标纵坐标。
+ * @return 当前界面是升级选择时返回 true，否则返回 false。
  */
 static bool HandleUpgradeClick(HWND hWnd, int mouseX, int mouseY)
 {
@@ -178,6 +199,7 @@ static bool HandleUpgradeClick(HWND hWnd, int mouseX, int mouseY)
         }
 
         upgradeUiState.selectedIndex = i;
+        // 多选强化先标记卡片，达到本次可选数量后再统一确认。
         if (upgradeUiState.picksRemaining > 1)
         {
             bool currentlyMarked = upgradeUiState.marked[i];
@@ -216,6 +238,10 @@ static bool HandleUpgradeClick(HWND hWnd, int mouseX, int mouseY)
 
 /**
  * @brief 处理暂停和结束覆盖层点击。
+ * @param hWnd 当前窗口句柄。
+ * @param mouseX 鼠标横坐标。
+ * @param mouseY 鼠标纵坐标。
+ * @return 点击命中覆盖层按钮返回 true，否则返回 false。
  */
 static bool HandleOverlayClick(HWND hWnd, int mouseX, int mouseY)
 {
@@ -286,6 +312,9 @@ static bool HandleOverlayClick(HWND hWnd, int mouseX, int mouseY)
 
 /**
  * @brief 处理鼠标左键释放事件，返回是否已处理。
+ * @param hWnd 当前窗口句柄。
+ * @param lParam 鼠标消息坐标参数。
+ * @return 事件已被界面逻辑消费返回 true，否则返回 false。
  */
 bool HandleMouseClick(HWND hWnd, LPARAM lParam)
 {
@@ -316,6 +345,8 @@ bool HandleMouseClick(HWND hWnd, LPARAM lParam)
 
 /**
  * @brief 处理鼠标滚轮事件。
+ * @param hWnd 当前窗口句柄。
+ * @param wParam 鼠标滚轮消息参数。
  */
 void HandleMouseWheel(HWND hWnd, WPARAM wParam)
 {
@@ -337,6 +368,9 @@ void HandleMouseWheel(HWND hWnd, WPARAM wParam)
 
 /**
  * @brief 处理主菜单键盘导航。
+ * @param hWnd 当前窗口句柄。
+ * @param key 按键虚拟键码。
+ * @return 当前界面是菜单时返回 true，否则返回 false。
  */
 static bool HandleMenuKey(HWND hWnd, WPARAM key)
 {
@@ -385,6 +419,9 @@ static bool HandleMenuKey(HWND hWnd, WPARAM key)
 
 /**
  * @brief 处理帮助和致谢页键盘导航。
+ * @param hWnd 当前窗口句柄。
+ * @param key 按键虚拟键码。
+ * @return 当前界面是帮助页时返回 true，否则返回 false。
  */
 static bool HandleRulesKey(HWND hWnd, WPARAM key)
 {
@@ -514,6 +551,9 @@ static bool HandleRulesKey(HWND hWnd, WPARAM key)
 
 /**
  * @brief 处理升级选择界面键盘导航。
+ * @param hWnd 当前窗口句柄。
+ * @param key 按键虚拟键码。
+ * @return 当前界面是升级选择时返回 true，否则返回 false。
  */
 static bool HandleUpgradeKey(HWND hWnd, WPARAM key)
 {
@@ -626,6 +666,8 @@ static bool HandleUpgradeKey(HWND hWnd, WPARAM key)
 
 /**
  * @brief 处理游戏过程中的按键。
+ * @param hWnd 当前窗口句柄。
+ * @param key 按键虚拟键码。
  */
 static void HandlePlayingKey(HWND hWnd, WPARAM key)
 {
@@ -709,6 +751,7 @@ static void HandlePlayingKey(HWND hWnd, WPARAM key)
         return;
     }
 
+    // 正常游玩按键先改变方块或触发技能，再统一刷新预测落点和界面。
     switch (key)
     {
     case VK_LEFT:
@@ -783,6 +826,8 @@ static void HandlePlayingKey(HWND hWnd, WPARAM key)
 
 /**
  * @brief 处理键盘按键事件。
+ * @param hWnd 当前窗口句柄。
+ * @param wParam 按键虚拟键码。
  */
 void HandleKeyDown(HWND hWnd, WPARAM wParam)
 {

src/source/app/TetrisLayout.cpp

@@ -1,8 +1,15 @@
 #include "stdafx.h"
+/**
+ * @file TetrisLayout.cpp
+ * @brief 实现窗口缩放布局和各类按钮、卡片、列表项的点击区域计算。
+ */
+
 #include "TetrisAppInternal.h"
 
 /**
  * @brief 将指定滚动偏移按步长调整，并限制在非负范围内。
+ * @param scrollOffset 需要修改的滚动偏移。
+ * @param delta 本次滚动增量。
  */
 void AdjustScrollOffset(int& scrollOffset, int delta)
 {
@@ -19,6 +26,9 @@ void AdjustScrollOffset(int& scrollOffset, int delta)
 
 /**
  * @brief 按当前窗口缩放返回一次滚动操作的像素距离。
+ * @param hWnd 当前窗口句柄。
+ * @param baseStep 设计稿中的基础滚动步长。
+ * @return 缩放后的滚动步长。
  */
 int GetScrollStep(HWND hWnd, int baseStep)
 {
@@ -28,6 +38,8 @@ int GetScrollStep(HWND hWnd, int baseStep)
 
 /**
  * @brief 根据当前窗口大小计算整体界面缩放与偏移。
+ * @param hWnd 当前窗口句柄。
+ * @return 布局缩放、偏移和网格尺寸。
  */
 LayoutMetrics GetLayoutMetrics(HWND hWnd)
 {
@@ -56,6 +68,9 @@ LayoutMetrics GetLayoutMetrics(HWND hWnd)
 
 /**
  * @brief 按当前布局比例缩放一个尺寸值。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿尺寸值。
+ * @return 缩放后的像素尺寸。
  */
 int ScaleValue(const LayoutMetrics& metrics, int value)
 {
@@ -64,6 +79,9 @@ int ScaleValue(const LayoutMetrics& metrics, int value)
 
 /**
  * @brief 按当前布局比例缩放横坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿横坐标。
+ * @return 实际窗口横坐标。
  */
 int ScaleXValue(const LayoutMetrics& metrics, int value)
 {
@@ -72,12 +90,20 @@ int ScaleXValue(const LayoutMetrics& metrics, int value)
 
 /**
  * @brief 按当前布局比例缩放纵坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿纵坐标。
+ * @return 实际窗口纵坐标。
  */
 int ScaleYValue(const LayoutMetrics& metrics, int value)
 {
     return metrics.offsetY + MulDiv(value, metrics.scale, 1000);
 }
 
+/**
+ * @brief 获取主菜单中央卡片区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 菜单卡片在窗口中的矩形区域。
+ */
 static RECT GetMenuCardRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -91,6 +117,12 @@ static RECT GetMenuCardRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取主菜单选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 菜单选项序号。
+ * @return 选项在窗口中的矩形区域。
+ */
 RECT GetMenuOptionRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -106,6 +138,11 @@ RECT GetMenuOptionRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页卡片区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 帮助卡片在窗口中的矩形区域。
+ */
 static RECT GetRulesCardRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -119,6 +156,12 @@ static RECT GetRulesCardRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页首页选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 帮助选项序号。
+ * @return 选项在窗口中的矩形区域。
+ */
 RECT GetHelpOptionRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -143,6 +186,12 @@ RECT GetHelpOptionRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取技能演示列表项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 技能演示条目序号。
+ * @return 条目在窗口中的矩形区域。
+ */
 RECT GetHelpSkillDemoItemRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -167,6 +216,11 @@ RECT GetHelpSkillDemoItemRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页底部返回提示的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回提示在窗口中的矩形区域。
+ */
 RECT GetHelpBackHintRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -181,6 +235,12 @@ RECT GetHelpBackHintRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取致谢页左右箭头按钮区域。
+ * @param hWnd 当前窗口句柄。
+ * @param direction 小于 0 为左箭头，大于 0 为右箭头。
+ * @return 箭头按钮在窗口中的矩形区域。
+ */
 RECT GetCreditArrowRect(HWND hWnd, int direction)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -201,6 +261,11 @@ RECT GetCreditArrowRect(HWND hWnd, int direction)
     return rect;
 }
 
+/**
+ * @brief 获取升级选择覆盖层区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 覆盖层在窗口中的矩形区域。
+ */
 static RECT GetUpgradeOverlayRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -214,6 +279,12 @@ static RECT GetUpgradeOverlayRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取升级选择卡片的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 强化卡片序号。
+ * @return 卡片在窗口中的矩形区域。
+ */
 RECT GetUpgradeCardRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -242,6 +313,11 @@ RECT GetUpgradeCardRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取暂停或结束提示覆盖层区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 覆盖层在窗口中的矩形区域。
+ */
 static RECT GetGameOverlayRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -260,6 +336,13 @@ static RECT GetGameOverlayRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取暂停或结束覆盖层按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 按钮序号。
+ * @param buttonCount 当前覆盖层按钮总数。
+ * @return 按钮在窗口中的矩形区域。
+ */
 RECT GetOverlayButtonRect(HWND hWnd, int index, int buttonCount)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -274,6 +357,11 @@ RECT GetOverlayButtonRect(HWND hWnd, int index, int buttonCount)
     return rect;
 }
 
+/**
+ * @brief 获取左上角返回按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回按钮在窗口中的矩形区域。
+ */
 RECT GetBackButtonRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -287,6 +375,11 @@ RECT GetBackButtonRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取右下角音乐按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 音乐按钮在窗口中的矩形区域。
+ */
 RECT GetMusicButtonRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -316,6 +409,13 @@ RECT GetMusicButtonRect(HWND hWnd)
     return buttonRect;
 }
 
+/**
+ * @brief 判断点坐标是否落在矩形内部。
+ * @param rect 待判断矩形。
+ * @param x 点的横坐标。
+ * @param y 点的纵坐标。
+ * @return 点在矩形内返回 true，否则返回 false。
+ */
 bool IsPointInRect(const RECT& rect, int x, int y)
 {
     return x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom;

src/source/app/TetrisMedia.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisMedia.cpp
+ * @brief 实现背景音乐开关和复活视频播放逻辑。
+ */
+
 #include "Tetris.h"
 #include "TetrisAppInternal.h"
 #include "TetrisAssets.h"
@@ -12,6 +17,9 @@ static constexpr const wchar_t* kReviveVideoAlias = L"TereisReviveVideo";
 
 /**
  * @brief 尝试通过 MCI 循环播放指定音乐文件。
+ * @param path 音频文件路径。
+ * @param forceMpegVideo 是否强制按 mpegvideo 类型打开。
+ * @return 播放成功返回 true，否则返回 false。
  */
 static bool TryPlayMciLoop(const std::wstring& path, bool forceMpegVideo)
 {
@@ -22,6 +30,7 @@ static bool TryPlayMciLoop(const std::wstring& path, bool forceMpegVideo)
 
     mciSendStringW((std::wstring(L"close ") + kBgmAlias).c_str(), nullptr, 0, nullptr);
 
+    // MCI 对部分 OGG/视频容器识别不稳定，调用方会按不同类型尝试。
     std::wstring openCommand = L"open \"" + path + L"\" ";
     if (forceMpegVideo)
     {
@@ -132,6 +141,7 @@ void StartBackgroundMusic()
 
 /**
  * @brief 切换背景音乐开关并刷新窗口。
+ * @param hWnd 当前窗口句柄。
  */
 void ToggleBackgroundMusic(HWND hWnd)
 {
@@ -149,6 +159,8 @@ void ToggleBackgroundMusic(HWND hWnd)
 
 /**
  * @brief 播放复活视频，先尝试 MCI，全屏播放失败时退回系统默认播放器。
+ * @param hWnd 当前窗口句柄，用作 MCI 父窗口和 ShellExecute 父窗口。
+ * @return 播放成功返回 true，否则返回 false。
  */
 bool PlayReviveVideo(HWND hWnd)
 {
@@ -176,6 +188,7 @@ bool PlayReviveVideo(HWND hWnd)
         StopBackgroundMusic();
     }
 
+    // 先用 MCI 全屏同步播放；失败时再交给系统默认播放器。
     bool played = false;
     for (int attempt = 0; attempt < 2 && !played; attempt++)
     {

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)
 {

src/source/common/TetrisAssets.cpp

@@ -1,8 +1,19 @@
 #include "stdafx.h"
+/**
+ * @file TetrisAssets.cpp
+ * @brief 实现资源路径解析和文件存在性检查，支持构建目录或项目根目录运行。
+ */
+
 #include "TetrisAssets.h"
 
 /**
  * @brief 根据程序所在目录拼出项目资源文件的绝对路径。
+ *
+ * 构建脚本会把可执行文件放到构建目录，因此这里先回到项目根目录，
+ * 再拼接 assets 下的图片、音频或视频路径。
+ *
+ * @param relativePath 相对于项目根目录的资源路径。
+ * @return 规范化后的绝对路径；解析失败时返回拼接路径。
  */
 std::wstring BuildAssetPath(const wchar_t* relativePath)
 {
@@ -16,6 +27,7 @@ std::wstring BuildAssetPath(const wchar_t* relativePath)
         basePath.resize(lastSlash);
     }
 
+    // 可执行文件位于构建目录，向上两级回到项目根目录。
     std::wstring projectRelative = basePath + L"\\..\\..\\" + relativePath;
     wchar_t fullPath[MAX_PATH] = {};
     DWORD result = GetFullPathNameW(projectRelative.c_str(), MAX_PATH, fullPath, nullptr);
@@ -29,6 +41,11 @@ std::wstring BuildAssetPath(const wchar_t* relativePath)
 
 /**
  * @brief 根据当前工作目录拼出项目资源文件的绝对路径。
+ *
+ * 这个路径用于从 IDE 或命令行直接以项目根目录运行时查找资源。
+ *
+ * @param relativePath 相对于当前工作目录的资源路径。
+ * @return 规范化后的绝对路径；解析失败时返回拼接路径。
  */
 std::wstring BuildWorkingDirAssetPath(const wchar_t* relativePath)
 {
@@ -52,6 +69,8 @@ std::wstring BuildWorkingDirAssetPath(const wchar_t* relativePath)
 
 /**
  * @brief 判断指定路径是否存在且不是目录。
+ * @param path 待检查的文件路径。
+ * @return 文件存在且不是目录返回 true，否则返回 false。
  */
 bool FileExists(const std::wstring& path)
 {

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)
 {

src/source/logic/TetrisPieceEffects.cpp

@@ -1,8 +1,16 @@
 #include "stdafx.h"
+/**
+ * @file TetrisPieceEffects.cpp
+ * @brief 实现彩虹、爆破、激光、十字和稳定结构等特殊方块落地效果。
+ */
+
 #include "TetrisLogicInternal.h"
 
 /**
  * @brief 结算彩虹方块固定后的染色和清除效果。
+ * @param overflowTop 固定时是否已经越过棋盘顶部。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
  */
 void ApplyRainbowLandingEffect(bool overflowTop, const Point* fixedCells, int fixedCellCount)
 {
@@ -11,6 +19,7 @@ void ApplyRainbowLandingEffect(bool overflowTop, const Point* fixedCells, int fi
         return;
     }
 
+    // 优先使用实际固定格子的平均行作为主色行，避免旋转形状偏移导致判定不自然。
     int rainbowAnchorRow = point.y + 1;
     if (fixedCellCount > 0)
     {
@@ -72,6 +81,8 @@ void ApplyRainbowLandingEffect(bool overflowTop, const Point* fixedCells, int fi
 
 /**
  * @brief 结算爆破方块的范围清除效果。
+ * @param explosiveCells 爆破方块写入棋盘的格子数组。
+ * @param explosiveCellCount 爆破格子数量。
  */
 static void ApplyExplosiveLandingEffect(const Point* explosiveCells, int explosiveCellCount)
 {
@@ -102,6 +113,7 @@ static void ApplyExplosiveLandingEffect(const Point* explosiveCells, int explosi
         explosiveExpGain);
     SetFeedbackMessage(_T("爆破核心"), explosiveDetail, 12);
 
+    // 连环炸弹需要等标准消行判断完成后，再决定是否追加一次小爆炸。
     if (rogueStats.chainBombLevel > 0 && explosiveCellCount > 0)
     {
         pendingChainBombCenter = explosiveCells[0];
@@ -111,6 +123,8 @@ static void ApplyExplosiveLandingEffect(const Point* explosiveCells, int explosi
 
 /**
  * @brief 结算激光方块的整列清除效果。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
  */
 static void ApplyLaserLandingEffect(const Point* fixedCells, int fixedCellCount)
 {
@@ -153,6 +167,8 @@ static void ApplyLaserLandingEffect(const Point* fixedCells, int fixedCellCount)
 
 /**
  * @brief 结算十字方块的整行整列清除效果。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
  */
 static void ApplyCrossLandingEffect(const Point* fixedCells, int fixedCellCount)
 {
@@ -225,6 +241,10 @@ static void ApplyStableStructureEffect()
 
 /**
  * @brief 结算爆破、激光、十字和稳定结构等特殊落地效果。
+ * @param fixedCells 当前方块写入棋盘的格子数组。
+ * @param fixedCellCount 写入棋盘的格子数量。
+ * @param explosiveCells 爆破方块写入棋盘的格子数组。
+ * @param explosiveCellCount 爆破格子数量。
  */
 void ApplySpecialLandingEffects(const Point* fixedCells, int fixedCellCount, const Point* explosiveCells, int explosiveCellCount)
 {

src/source/render/TetrisRenderAssets.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisRenderAssets.cpp
+ * @brief 实现 GDI+ 初始化以及背景图、致谢页图片的加载与缓存。
+ */
+
 #include "TetrisRenderInternal.h"
 #include "TetrisAssets.h"
 #include <objidl.h>
@@ -10,6 +15,8 @@ using namespace Gdiplus;
 
 /**
  * @brief 尝试从指定路径加载 GDI+ 位图。
+ * @param path 图片文件路径。
+ * @return 加载成功返回位图指针，失败返回 nullptr。
  */
 static Bitmap* TryLoadBitmap(const std::wstring& path)
 {
@@ -30,6 +37,7 @@ static Bitmap* TryLoadBitmap(const std::wstring& path)
 
 /**
  * @brief 确保 GDI+ 已初始化，返回初始化是否成功。
+ * @return GDI+ 可用返回 true，否则返回 false。
  */
 static bool EnsureGdiplusStarted()
 {
@@ -39,6 +47,7 @@ static bool EnsureGdiplusStarted()
 
     if (!attempted)
     {
+        // GDI+ 只需要初始化一次，静态标记避免重复启动。
         attempted = true;
         GdiplusStartupInput startupInput;
         started = GdiplusStartup(&gdiplusToken, &startupInput, nullptr) == Ok;
@@ -49,6 +58,7 @@ static bool EnsureGdiplusStarted()
 
 /**
  * @brief 加载并缓存主背景图片。
+ * @return 成功时返回缓存位图指针，失败时返回 nullptr。
  */
 Bitmap* LoadBackgroundImage()
 {
@@ -69,6 +79,7 @@ Bitmap* LoadBackgroundImage()
                 BuildWorkingDirAssetPath(L"assets\\images\\background.bmp")
             };
 
+            // 同时支持构建目录运行和项目根目录运行两种启动方式。
             for (const std::wstring& candidate : candidates)
             {
                 backgroundImage = TryLoadBitmap(candidate);
@@ -85,6 +96,8 @@ Bitmap* LoadBackgroundImage()
 
 /**
  * @brief 按序号加载并缓存致谢页图片。
+ * @param index 致谢页图片序号。
+ * @return 成功时返回缓存位图指针，失败或越界时返回 nullptr。
  */
 Bitmap* LoadCreditImage(int index)
 {
@@ -123,6 +136,7 @@ Bitmap* LoadCreditImage(int index)
             };
             int candidateCount = (index == 3) ? 8 : 2;
 
+            // 第四张致谢图历史上有多种扩展名，这里保留兼容查找。
             for (int i = 0; i < candidateCount; i++)
             {
                 creditImages[index] = TryLoadBitmap(creditExtraCandidates[i]);

src/source/rogue/TetrisRogue.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisRogue.cpp
+ * @brief 实现 Rogue 模式的强化池、等级成长、特殊方块、主动技能、难度和技能演示。
+ */
+
 #include "TetrisLogicInternal.h"
 
 /**
@@ -1513,6 +1518,8 @@ static int GetRogueExpByLines(int linesCleared)
 
 /**
  * @brief 结算经验条并返回本次连续升级次数。
+ * @param stats 需要结算经验的玩家统计。
+ * @return 本次触发的升级次数。
  */
 static int ApplyLevelProgress(PlayerStats& stats)
 {
@@ -1531,6 +1538,8 @@ static int ApplyLevelProgress(PlayerStats& stats)
 
 /**
  * @brief 触发升级冲击波，清除底部指定数量的行。
+ * @param rowsToClear 需要清除的底部行数。
+ * @return 实际清除的行数。
  */
 static int TriggerUpgradeShockwave(int rowsToClear)
 {
@@ -1547,6 +1556,9 @@ static int TriggerUpgradeShockwave(int rowsToClear)
 
 /**
  * @brief 按权重和当前局势生成升级菜单中的候选强化。
+ *
+ * 该函数只负责生成 UI 选项，不应用强化效果。候选池会先过滤前置、
+ * 等级上限和互斥条件，再按动态权重不放回抽取，保证同一轮不会重复出现。
  */
 static void FillUpgradeOptions()
 {
@@ -1554,6 +1566,7 @@ static void FillUpgradeOptions()
     int selectableWeights[kUpgradePoolSize] = { 0 };
     int selectableCount = 0;
 
+    // 第一段：筛出当前真正可选的强化，并记录它们的动态权重。
     for (int i = 0; i < kUpgradePoolSize; i++)
     {
         if (IsUpgradeSelectable(kUpgradePool[i]))
@@ -1564,6 +1577,7 @@ static void FillUpgradeOptions()
         }
     }
 
+    // 命运轮盘把候选扩到 6 个；双重抉择和命运轮盘都会允许本轮选 2 个。
     int optionLimit = (rogueStats.destinyWheelLevel > 0) ? 6 : 3;
     int optionCount = selectableCount < optionLimit ? selectableCount : optionLimit;
     upgradeUiState.optionCount = optionCount;
@@ -1575,6 +1589,7 @@ static void FillUpgradeOptions()
         upgradeUiState.marked[i] = false;
     }
 
+    // 第二段：按权重不放回抽取候选，抽中后用末尾元素覆盖当前槽位。
     for (int i = 0; i < optionCount; i++)
     {
         int totalWeight = 0;
@@ -1612,6 +1627,7 @@ static void FillUpgradeOptions()
         upgradeUiState.options[i].category = pickedEntry.category;
         upgradeUiState.options[i].description = pickedEntry.description;
 
+        // 方块改造目前固定展示 I 块概率提升，说明文字需要运行时拼接。
         if (pickedEntry.id == UPGRADE_PIECE_TUNING)
         {
             int targetPieceType = 0;
@@ -1632,6 +1648,7 @@ static void FillUpgradeOptions()
         selectableCount--;
     }
 
+    // 命运轮盘在候选中随机附加一个诅咒，确认时才提高下一次升级需求。
     if (rogueStats.destinyWheelLevel > 0 && optionCount > 0)
     {
         int cursedIndex = rand() % optionCount;
@@ -1641,6 +1658,7 @@ static void FillUpgradeOptions()
 
 /**
  * @brief 综合难度、强化和临时状态计算 Rogue 模式下落间隔。
+ * @return 当前应使用的下落计时器间隔，单位毫秒。
  */
 int GetRogueFallInterval()
 {
@@ -1692,14 +1710,24 @@ int GetRogueFallInterval()
 
 /**
  * @brief 根据强化编号把对应效果写入 Rogue 属性。
+ *
+ * 该函数集中修改 Rogue 属性和少量即时棋盘效果。调用者已经完成赌徒契约、
+ * 多选确认和诅咒处理，因此这里保持强化效果本身的顺序和数值不变。
+ *
+ * @param upgradeId 强化编号。
+ * @param targetPieceType 方块改造目标方块类型；当前实现固定使用 I 块。
+ * @param applyCount 本次效果应用次数，赌徒落空时可能为 0。
  */
 static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
 {
+    (void)targetPieceType;
+
     if (applyCount <= 0)
     {
         return;
     }
 
+    // 基础成长类强化直接叠加倍率或层数。
     switch (upgradeId)
     {
     case UPGRADE_SCORE_MULTIPLIER:
@@ -1738,6 +1766,7 @@ static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
         break;
     case UPGRADE_PRESSURE_RELIEF:
     {
+        // 卸压清场立即从最高占用行开始删除，直接改善当前局面。
         rogueStats.pressureReliefLevel += applyCount;
         for (int i = 0; i < applyCount; i++)
         {
@@ -1838,6 +1867,7 @@ static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
         rogueStats.previewUpgradeLevel = rogueStats.previewCount - 1;
         break;
     case UPGRADE_BLOCK_STORM:
+        // 方块风暴会同时改写预览队列，确保玩家马上看到连续 I 块。
         rogueStats.blockStormLevel = 1;
         rogueStats.blockStormPiecesRemaining = 5;
         nextTypes[0] = 0;
@@ -1886,6 +1916,10 @@ static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
 
 /**
  * @brief 为技能清除的格子结算得分和经验奖励。
+ * @param clearedCells 清除格子数。
+ * @param scoreGain 返回本次得分增量。
+ * @param expGain 返回本次经验增量。
+ * @param allowLevelProgress 是否允许本次奖励触发升级流程。
  */
 void AwardRogueSkillClearRewards(int clearedCells, int& scoreGain, int& expGain, bool allowLevelProgress)
 {
@@ -1968,6 +2002,7 @@ void CheckRogueLevelProgress()
 
     upgradeUiState.pendingCount += levelUps;
 
+    // 升级冲击波和进化冲击延后到升级菜单关闭后播放，避免菜单遮挡反馈。
     int shockwaveRows = 0;
     if (rogueStats.evolutionImpactLevel > 0)
     {
@@ -2033,6 +2068,7 @@ void ApplyBoardGravity()
 
 /**
  * @brief 结算一次标准消行带来的 Rogue 得分、经验、连击和派生效果。
+ * @param linesCleared 本次标准消行数量。
  */
 void ApplyLineClearResult(int linesCleared)
 {
@@ -2053,6 +2089,7 @@ void ApplyLineClearResult(int linesCleared)
         return;
     }
 
+    // 基础收益先计算，再依次套用风险、成长、狂热、赌徒和连击类修正。
     int scoreGain = GetRogueScoreByLines(linesCleared);
     scoreGain = scoreGain * rogueStats.scoreMultiplierPercent / 100;
 
@@ -2438,6 +2475,9 @@ void OpenUpgradeMenu()
 
 /**
  * @brief 确认升级菜单中的选择并应用对应强化效果。
+ *
+ * 多选流程会先检查标记数量，再按卡片顺序逐个应用；单选流程应用后会移除
+ * 当前卡片。所有待升级次数结算完成后，才恢复游戏、播放暂存消行动画和冲击波。
  */
 void ConfirmUpgradeSelection()
 {
@@ -2446,6 +2486,7 @@ void ConfirmUpgradeSelection()
         return;
     }
 
+    // 命运轮盘或双重抉择使用多选分支，避免选完第一张后候选池被立即刷新。
     if (upgradeUiState.picksRemaining > 1)
     {
         if (upgradeUiState.markedCount != upgradeUiState.picksRemaining)
@@ -2522,6 +2563,7 @@ void ConfirmUpgradeSelection()
         return;
     }
 
+    // 普通升级只应用当前高亮卡片，并把剩余卡片前移，支持后续 picksRemaining。
     UpgradeOption selectedOption = upgradeUiState.options[upgradeUiState.selectedIndex];
     TCHAR gamblerSuffix[64] = _T("");
     int applyCount = RollGamblerApplyCount(gamblerSuffix, 64, false);
@@ -2580,6 +2622,7 @@ void ConfirmUpgradeSelection()
         return;
     }
 
+    // 连续升级时重新生成下一轮强化；全部完成后回到游戏并播放延迟效果。
     if (upgradeUiState.pendingCount > 0)
     {
         upgradeUiState.pendingCount--;

src/source/stdafx.cpp

@@ -1,6 +1,7 @@
-// stdafx.cpp : 只包括标准包含文件的源文件
-// Tetris.pch 将作为预编译头
-// stdafx.obj 将包含预编译类型信息
+/**
+ * @file stdafx.cpp
+ * @brief 预编译头源文件，只包含 stdafx.h 以生成共享编译信息。
+ */
 
 #include "stdafx.h"