补强注释

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