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
@@ -1,4 +1,4 @@
-using Ink_Canvas.Helpers;
+using Ink_Canvas.Helpers;
 using iNKORE.UI.WPF.Modern;
 using System;
 using System.Threading;
@@ -13,9 +13,31 @@ namespace Ink_Canvas
 {
    public partial class MainWindow : Window
    {
+        /// <summary>
+        /// 浮动栏是否折叠的标志。
+        /// </summary>
        public bool isFloatingBarFolded;
+        
+        /// <summary>
+        /// 浮动栏正在改变隐藏模式的标志，用于防止重复操作。
+        /// </summary>
        private bool isFloatingBarChangingHideMode;

+        /// <summary>
+        /// 立即关闭白板模式，恢复到批注模式。
+        /// </summary>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查是否正在显示或隐藏黑板，如果是则直接返回
+        /// 2. 设置显示/隐藏黑板的标志为true
+        /// 3. 立即隐藏所有子面板
+        /// 4. 如果启用了自动切换多指手势，则关闭多指平移
+        /// 5. 隐藏所有水印
+        /// 6. 切换到批注模式
+        /// 7. 设置退出按钮前景色为白色
+        /// 8. 设置应用主题为深色
+        /// 9. 200毫秒后重置显示/隐藏黑板的标志为false
+        /// </remarks>
        private void CloseWhiteboardImmediately()
        {
            if (isDisplayingOrHidingBlackboard) return;
@@ -38,11 +60,35 @@ namespace Ink_Canvas
            }).Start();
        }

+        /// <summary>
+        /// 处理折叠浮动栏的鼠标点击事件。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="e">鼠标按钮事件参数。</param>
        public async void FoldFloatingBar_MouseUp(object sender, MouseButtonEventArgs e)
        {
            await FoldFloatingBar(sender);
        }

+        /// <summary>
+        /// 折叠浮动栏，将其收纳到侧边栏。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="isAutoFoldCommand">是否为自动折叠命令。</param>
+        /// <returns>表示异步操作的任务。</returns>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查是否应该拒绝操作（如点击了折叠图标但上次鼠标按下的对象不是折叠图标）
+        /// 2. 设置折叠/展开标志
+        /// 3. 检查浮动栏是否已经折叠或正在改变隐藏模式，如果是则直接返回
+        /// 4. 处理墨迹重放相关的UI元素
+        /// 5. 设置浮动栏状态标志，关闭白板模式（如果当前在白板模式）
+        /// 6. 如果是用户手动折叠且画布上有较多墨迹，显示通知
+        /// 7. 清空画布墨迹
+        /// 8. 隐藏PPT导航面板和浮动栏拖动网格
+        /// 9. 执行浮动栏和侧边栏的动画
+        /// 10. 如果开启了彻底隐藏，则隐藏主窗口
+        /// </remarks>
        public async Task FoldFloatingBar(object sender, bool isAutoFoldCommand = false)
        {
            var isShouldRejectAction = false;
@@ -122,6 +168,17 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 处理左侧展开按钮显示快捷面板的鼠标点击事件。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="e">鼠标按钮事件参数。</param>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查是否显示快捷面板
+        /// 2. 如果显示快捷面板，则隐藏右侧快捷面板，显示左侧快捷面板并执行动画
+        /// 3. 否则，调用展开浮动栏的方法
+        /// </remarks>
        private async void LeftUnFoldButtonDisplayQuickPanel_MouseUp(object sender, MouseButtonEventArgs e)
        {
            if (Settings.Appearance.IsShowQuickPanel)
@@ -152,6 +209,17 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 处理右侧展开按钮显示快捷面板的鼠标点击事件。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="e">鼠标按钮事件参数。</param>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查是否显示快捷面板
+        /// 2. 如果显示快捷面板，则隐藏左侧快捷面板，显示右侧快捷面板并执行动画
+        /// 3. 否则，调用展开浮动栏的方法
+        /// </remarks>
        private async void RightUnFoldButtonDisplayQuickPanel_MouseUp(object sender, MouseButtonEventArgs e)
        {
            if (Settings.Appearance.IsShowQuickPanel)
@@ -182,6 +250,15 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 隐藏左侧快捷面板。
+        /// </summary>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查左侧快捷面板是否可见，如果不可见则直接返回
+        /// 2. 执行左侧快捷面板的隐藏动画
+        /// 3. 等待动画完成后，设置左侧快捷面板的边距并将其折叠
+        /// </remarks>
        private async void HideLeftQuickPanel()
        {
            if (LeftUnFoldButtonQuickPanel.Visibility == Visibility.Visible)
@@ -207,6 +284,15 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 隐藏右侧快捷面板。
+        /// </summary>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 检查右侧快捷面板是否可见，如果不可见则直接返回
+        /// 2. 执行右侧快捷面板的隐藏动画
+        /// 3. 等待动画完成后，设置右侧快捷面板的边距并将其折叠
+        /// </remarks>
        private async void HideRightQuickPanel()
        {
            if (RightUnFoldButtonQuickPanel.Visibility == Visibility.Visible)
@@ -232,17 +318,50 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 处理隐藏快捷面板的鼠标点击事件。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="e">鼠标按钮事件参数。</param>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 隐藏左侧快捷面板
+        /// 2. 隐藏右侧快捷面板
+        /// </remarks>
        private void HideQuickPanel_MouseUp(object sender, MouseButtonEventArgs e)
        {
            HideLeftQuickPanel();
            HideRightQuickPanel();
        }

+        /// <summary>
+        /// 处理展开浮动栏的鼠标点击事件。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <param name="e">鼠标按钮事件参数。</param>
        public async void UnFoldFloatingBar_MouseUp(object sender, MouseButtonEventArgs e)
        {
            await UnFoldFloatingBar(sender);
        }

+        /// <summary>
+        /// 展开浮动栏，将其从侧边栏恢复到正常状态。
+        /// </summary>
+        /// <param name="sender">事件发送者。</param>
+        /// <returns>表示异步操作的任务。</returns>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 如果之前彻底隐藏了主窗口，先恢复显示
+        /// 2. 隐藏左右侧快捷面板
+        /// 3. 设置展开/折叠标志
+        /// 4. 检查浮动栏是否正在改变隐藏模式，如果是则直接返回
+        /// 5. 设置浮动栏状态标志，标记为未折叠
+        /// 6. 根据设置决定是否自动切换至批注模式
+        /// 7. 根据PPT放映模式和设置显示或隐藏翻页按钮
+        /// 8. 在屏幕模式下显示浮动栏并执行动画
+        /// 9. 执行侧边栏动画
+        /// 10. 等待UI完全更新后，重新设置当前选中模式的按钮高亮状态
+        /// </remarks>
        public async Task UnFoldFloatingBar(object sender)
        {
            // 新增：如果之前彻底隐藏了，先恢复显示
@@ -356,6 +475,21 @@ namespace Ink_Canvas

        }

+        /// <summary>
+        /// 执行侧边栏边距动画，用于折叠或展开侧边栏。
+        /// </summary>
+        /// <param name="MarginFromEdge">侧边栏距边缘的边距值。可能的值：-50（完全折叠）, -10（半展开）</param>
+        /// <param name="isNoAnimation">是否禁用动画效果。</param>
+        /// <remarks>
+        /// 操作包括：
+        /// 1. 如果边距值为-10（半展开），则显示左侧边栏
+        /// 2. 创建并执行左侧边栏的边距动画
+        /// 3. 创建并执行右侧边栏的边距动画
+        /// 4. 等待600毫秒让动画完成
+        /// 5. 直接设置侧边栏的最终边距值
+        /// 6. 如果边距值为-50（完全折叠），则隐藏左侧边栏
+        /// 7. 重置浮动栏正在改变隐藏模式的标志为false
+        /// </remarks>
        private async void SidePannelMarginAnimation(int MarginFromEdge, bool isNoAnimation = false) // Possible value: -50, -10
        {
            await Dispatcher.InvokeAsync(() =>