feat(docstring):添加部分docstring (#376)

* feat(docstring):添加docstring Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * fix(docstring):修复部分docstring格式错误 Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * fix(docstring):修复部分docstring Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * chore(Docstring):MW_* 前14 * chore(Docstring):MW_* part 2 * chore(Docstring):MW_* part 3 * chore:优化缩进 * fix: 修复数学计算中的潜在除零错误和数值稳定性问题 Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * chore:删除Rebase时多余的OOBE函数 * chore: 更新代码注释和文档格式修复XML文档注释中的格式问题，统一使用<c>和<see>标签更新ConfigHelper类的预留说明，明确未来扩展用途优化TimerDisplayDate_Elapsed方法的注释，说明UI异步更新机制合并重复的注释摘要行，提高文档可读性添加形状识别功能的64位进程限制说明修正视频呈现器设备选择逻辑的文档说明 * chore(IPPTLinkManager): 更新TryEndSlideShow方法的XML注释格式 * chore: 修正代码注释中的术语和格式问题更新多个文件中的XML注释，统一使用<see langword="..."/>标记代替<c>...</c>标记规范术语使用（如"延迟初始化"代替"懒惰初始化"）修正注释中的格式错误和补充说明调整代码区域的注释对齐格式 --------- Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com>
2026-02-22 10:14:12 +08:00
parent 3e3db27296
commit 656863a7d0
48 changed files with 6220 additions and 192 deletions
@@ -46,11 +46,18 @@ namespace Ink_Canvas.Helpers
        #endregion

        #region Constructor
+        /// <summary>
+        /// 初始化 PPTInkManager 实例并为内部内存流分配初始容量以跟踪默认最大幻灯片数加上备用槽位。
+        /// </summary>
        public PPTInkManager()
        {
            InitializeMemoryStreams(DefaultMaxSlides + 2);
        }

+        /// <summary>
+        /// 根据指定容量初始化用于存储每页墨迹的内存流数组。
+        /// </summary>
+        /// <param name="capacity">期望的数组容量；如果小于 2，则会使用 2 作为最小容量。</param>
        private void InitializeMemoryStreams(int capacity)
        {
            if (_memoryStreams != null)
@@ -69,6 +76,12 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 初始化新的演示文稿
        /// </summary>
+        /// <remarks>
+        /// 为新的或当前的演示文稿初始化墨迹管理器的内部状态。
+        /// 方法会清除所有内存中的笔迹数据，重置墨迹写入锁与快速切换追踪，并根据演示文稿的幻灯片数量分配内部内存缓冲区。
+        /// 如果已启用自动保存且设置了 <see cref="AutoSaveLocation"/>，则会尝试加载磁盘上的已保存墨迹文件。
+        /// </remarks>
+        /// <param name="presentation">要初始化的 PowerPoint Presentation 实例；为 null 时方法不执行任何操作并直接返回。</param>
        public void InitializePresentation(Presentation presentation)
        {
            ThrowIfDisposed();
@@ -115,6 +128,11 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 保存当前页面的墨迹
        /// </summary>
+        /// <remarks>
+        /// 将指定幻灯片的墨迹保存到内部内存缓存，并在必要时触发内存清理。
+        /// </remarks>
+        /// <param name="slideIndex">要保存的幻灯片索引（从 1 开始）。方法在索引小于或等于 0 时不执行任何操作。</param>
+        /// <param name="strokes">要保存的墨迹集合；为 null 时方法不执行任何操作。</param>
        public void SaveCurrentSlideStrokes(int slideIndex, StrokeCollection strokes)
        {
            ThrowIfDisposed();
@@ -140,6 +158,11 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 强制保存指定页墨迹到内存（不受锁定限制）。用于放映结束前保存当前画布到当前页。
        /// </summary>
+        /// <remarks>
+        /// 强制将指定幻灯片的墨迹保存到内部内存缓存，覆盖该幻灯片已有的墨迹数据。
+        /// </remarks>
+        /// <param name="slideIndex">要保存的幻灯片索引（从 1 开始）。</param>
+        /// <param name="strokes">要保存的墨迹集合，不能为空。</param>
        public void ForceSaveSlideStrokes(int slideIndex, StrokeCollection strokes)
        {
            ThrowIfDisposed();
@@ -163,6 +186,11 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 加载指定页面的墨迹
        /// </summary>
+        /// <remarks>
+        /// 加载并返回指定幻灯片的墨迹集合。
+        /// </remarks>
+        /// <param name="slideIndex">要加载的幻灯片索引（从1开始）。</param>
+        /// <returns>包含指定幻灯片的墨迹的 StrokeCollection；如果该幻灯片没有已保存的墨迹或加载失败，则返回空的 StrokeCollection。</returns>
        public StrokeCollection LoadSlideStrokes(int slideIndex)
        {
            ThrowIfDisposed();
@@ -190,6 +218,12 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 切换到指定页面并加载墨迹
        /// </summary>
+        /// <remarks>
+        /// 切换到指定幻灯片并返回该幻灯片的已加载笔迹集合。
+        /// </remarks>
+        /// <param name="slideIndex">要切换到的幻灯片索引（从 1 开始）。</param>
+        /// <param name="currentStrokes">可选的当前笔迹集合，用于在切换时提供当前画面状态。</param>
+        /// <returns>`StrokeCollection`：指定幻灯片已加载的笔迹集合；若加载失败则返回一个空的 `StrokeCollection`。</returns>
        public StrokeCollection SwitchToSlide(int slideIndex, StrokeCollection currentStrokes = null)
        {
            ThrowIfDisposed();
@@ -221,8 +255,12 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 保存所有墨迹到文件
        /// </summary>
-        /// <param name="presentation">演示文稿对象</param>
-        /// <param name="currentSlideIndex">当前播放的页码，如果提供则使用此值保存位置，否则使用_lockedSlideIndex</param>
+        /// <remarks>
+        /// 将内存中当前演示文稿的每页墨迹保存到磁盘，并根据情况写入当前播放位置文件。
+        /// 仅在 IsAutoSaveEnabled 为真且 AutoSaveLocation 已设置时执行。会在演示文稿专属文件夹中写入按页编号的墨迹文件（带 `.icstk` 扩展名）和可选的 Position 文件。遇到特定 COM 错误（HRESULT 0x80048010）时会中止保存当前幻灯片计数读取而不抛出异常；单页保存失败会记录错误并继续处理其他页。
+        /// </remarks>
+        /// <param name="presentation">要保存墨迹的 PowerPoint 演示文稿对象。</param>
+        /// <param name="currentSlideIndex">当前播放的页码；如果大于 0 则以此值写入 Position 文件，否则使用当前被锁定的页码或最后切换的页码作为保存位置。</param>
        public void SaveAllStrokesToFile(Presentation presentation, int currentSlideIndex = -1)
        {
            ThrowIfDisposed();
@@ -288,6 +326,12 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 从文件加载已保存的墨迹
        /// </summary>
+        /// <remarks>
+        /// 从自动保存目录加载已保存的幻灯片墨迹数据到内存流中，供后续显示和编辑使用。
+        /// 仅在启用自动保存且已设置 AutoSaveLocation 时执行。函数获取当前演示文稿的自动保存文件夹，遍历以 <c>.icstk</c> 为扩展名的文件，
+        /// 将文件名（去除扩展名）解析为幻灯片索引并在合法且文件大小大于 8 字节时加载到对应的内存流槽位。对单个文件的读取失败会记录错误并继续处理其他文件；
+        /// 若成功加载则会记录已加载页数。方法在内部使用锁以保证线程安全。
+        /// </remarks>
        public void LoadSavedStrokes()
        {
            ThrowIfDisposed();
@@ -337,6 +381,10 @@ namespace Ink_Canvas.Helpers
        /// <summary>
        /// 清除所有墨迹
        /// </summary>
+        /// <remarks>
+        /// 清除并释放当前演示文稿所有幻灯片的墨迹数据和相关内存资源。
+        /// 该方法在内部加锁以保证线程安全；会处置并清空所有内部存储的墨迹流、重建内部流数组并清空 CurrentStrokes。
+        /// </remarks>
        public void ClearAllStrokes()
        {
            ThrowIfDisposed();
@@ -346,6 +394,10 @@ namespace Ink_Canvas.Helpers
            }
        }

+        /// <summary>
+        /// 为指定幻灯片设置短时墨迹写入锁，防止在该时间窗口内对其他幻灯片进行写入操作。
+        /// </summary>
+        /// <param name="slideIndex">要上锁的幻灯片索引（大于 0）。锁从调用时刻开始，持续 InkLockMilliseconds 毫秒。</param>
        public void LockInkForSlide(int slideIndex)
        {
            ThrowIfDisposed();
@@ -353,6 +405,11 @@ namespace Ink_Canvas.Helpers
            _lockedSlideIndex = slideIndex;
        }

+        /// <summary>
+        /// 确定在当前滑页上下文中是否允许写入墨迹（基于短期的墨迹写入锁与容差窗口）。
+        /// </summary>
+        /// <param name="currentSlideIndex">当前尝试写入墨迹的幻灯片索引（从 1 开始）。</param>
+        /// <returns>`true` 如果允许写入墨迹（锁已过期、目标为被锁定的幻灯片，或处于短暂的容差窗口内），`false` 否则。</returns>
        public bool CanWriteInk(int currentSlideIndex)
        {
            ThrowIfDisposed();
@@ -362,6 +419,12 @@ namespace Ink_Canvas.Helpers
            return false;
        }

+        /// <summary>
+        /// 重置与墨迹书写和幻灯片切换相关的锁与跟踪状态为初始（未锁定）值。
+        /// </summary>
+        /// <remarks>
+        /// 将内部的墨迹写入到期时间、当前被锁定的幻灯片索引、上次切换时间和上次切换的幻灯片索引均恢复为默认未设置状态。
+        /// </remarks>
        public void ResetLockState()
        {
            ThrowIfDisposed();
@@ -378,6 +441,14 @@ namespace Ink_Canvas.Helpers

        #region Private Helpers

+        /// <summary>
+        /// 释放并清除类内用于存储各页墨迹的所有内存流，清空当前画笔集合，并重置内部内存流数组容量为 _maxSlides + 2。
+        /// </summary>
+        /// <remarks>
+        /// - 会逐个释放已存在的 MemoryStream（忽略释放过程中的异常），并将对应槽位设为 null。
+        /// - 会清空 CurrentStrokes 集合。 
+        /// - 会记录一条跟踪日志，指示已完成清除操作。
+        /// </remarks>
        private void ClearAllStrokesInternal()
        {
            if (_memoryStreams != null)
@@ -393,6 +464,11 @@ namespace Ink_Canvas.Helpers
            LogHelper.WriteLogToFile("已清除所有墨迹", LogHelper.LogType.Trace);
        }

+        /// <summary>
+        /// 用指定的笔迹集合替换内部存储中对应幻灯片索引的内存流：释放（并忽略释放错误）旧流，将 <paramref name="strokes"/> 序列化到新的 <see cref="MemoryStream"/> 并保存回内部数组。
+        /// </summary>
+        /// <param name="slideIndex">要替换的幻灯片索引（内部内存流数组的索引）。</param>
+        /// <param name="strokes">要序列化并保存到内存流的笔迹集合。</param>
        private void ReplaceSlideStream(int slideIndex, StrokeCollection strokes)
        {
            try { _memoryStreams[slideIndex]?.Dispose(); } catch (Exception ex) { LogHelper.WriteLogToFile($"释放旧内存流失败: {ex}", LogHelper.LogType.Warning); }
@@ -402,6 +478,11 @@ namespace Ink_Canvas.Helpers
            _memoryStreams[slideIndex] = ms;
        }

+        /// <summary>
+        /// 从指定文件夹删除对应幻灯片的笔迹文件（按四位索引命名）；如果文件不存在或删除失败则静默忽略错误。
+        /// </summary>
+        /// <param name="folderPath">存放笔迹文件的文件夹路径。</param>
+        /// <param name="slideIndex">用于生成文件名的幻灯片索引（格式化为四位，例如 1 -> "0001"）。</param>
        private void TryDeleteStrokeFile(string folderPath, int slideIndex)
        {
            try
@@ -412,6 +493,12 @@ namespace Ink_Canvas.Helpers
            catch (Exception ex) { System.Diagnostics.Debug.WriteLine(ex); }
        }

+        /// <summary>
+        /// 检查当前墨迹内存使用状况并在超过阈值时触发清理操作。
+        /// </summary>
+        /// <remarks>
+        /// 会更新内部的内存使用统计并刷新上次清理时间；当总占用超过 MaxMemoryUsageBytes 时，会记录警告并调用 CleanupInactiveSlideStrokes 清理不活跃幻灯页的墨迹流。若检查或清理过程中发生异常，会记录错误日志。
+        /// </remarks>
        private void CheckAndPerformMemoryCleanup()
        {
            try
@@ -440,6 +527,12 @@ namespace Ink_Canvas.Helpers
            }
        }

+        /// <summary>
+        /// 清理不活跃幻灯片的内存化墨迹数据以回收内存空间。
+        /// </summary>
+        /// <remarks>
+        /// 将释放除当前锁定幻灯片与最近切换幻灯片之外的每页内存流（若存在），并将对应数组项设为 null；完成后若有释放，会记录已清理页数与释放的总大小（KB）。
+        /// </remarks>
        private void CleanupInactiveSlideStrokes()
        {
            if (_memoryStreams == null) return;
@@ -459,6 +552,10 @@ namespace Ink_Canvas.Helpers
                LogHelper.WriteLogToFile($"已清理 {cleaned} 页墨迹，释放 {freed / 1024}KB", LogHelper.LogType.Trace);
        }

+        /// <summary>
+        /// 生成基于演示文稿名称、幻灯片数量和路径哈希的标识符字符串。
+        /// </summary>
+        /// <returns>由 `名称_幻灯片数_路径哈希` 组成的标识符；若生成失败则返回形如 `unknown_{ticks}` 的回退标识符。</returns>
        private string GeneratePresentationId(Presentation presentation)
        {
            try
@@ -483,6 +580,12 @@ namespace Ink_Canvas.Helpers

        #region Dispose

+        /// <summary>
+        /// 释放 PPTInkManager 持有的资源并清除所有内存中的笔迹数据。
+        /// </summary>
+        /// <remarks>
+        /// 调用后该实例将进入已释放状态，不应再被使用。方法为幂等且线程安全：如果已释放则立即返回，否则在同步区内清理资源并标记为已释放。
+        /// </remarks>
        public void Dispose()
        {
            if (_disposed) return;
@@ -498,4 +601,4 @@ namespace Ink_Canvas.Helpers

        #endregion
    }
-}
+}