补强注释

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