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
@@ -20,8 +20,11 @@ namespace Ink_Canvas
        ObservableCollection<PageListViewItem> blackBoardSidePageListViewObservableCollection = new ObservableCollection<PageListViewItem>();

        /// <summary>
-        /// <para>刷新白板的缩略图页面列表。</para>
+        /// 刷新白板的缩略图页面列表，更新左右侧缩略页列表，使其与当前白板页及历史快照一致，并将左右列表的选中项同步到当前白板页。
        /// </summary>
+        /// <remarks>
+        /// 为每页生成或更新对应的 PageListViewItem（通过应用时间线历史并裁剪到画布边界），用当前画布的笔迹替换当前页的条目，并将两个侧边 ListView 的 SelectedIndex 设置为当前白板索引 - 1。
+        /// </remarks>
        private void RefreshBlackBoardSidePageListView()
        {
            if (blackBoardSidePageListViewObservableCollection.Count == WhiteboardTotalCount)
@@ -67,6 +70,16 @@ namespace Ink_Canvas
            BlackBoardRightSidePageListView.SelectedIndex = CurrentWhiteboardIndex - 1;
        }

+        /// <summary>
+        /// 根据传入相对于 <paramref name="scrollViewer"/> 的点，查找并选中列表中对应的缩略图项；在需要时切换当前白板页并更新画布状态与左右侧缩略图选择状态。
+        /// </summary>
+        /// <param name="listView">承载页面缩略图的 ListView。</param>
+        /// <param name="scrollViewer">包含该 ListView 的 ScrollViewer，用于将触点坐标从滚动视图坐标系转换到 ListView。</param>
+        /// <param name="pointInScrollViewer">相对于 <paramref name="scrollViewer"/> 的触点坐标（用于命中测试）。</param>
+        /// <remarks>
+        /// - 如果命中到 ListViewItem，会隐藏左右侧页面边框、在必要时保存/清空/恢复画笔笔迹并更新 CurrentWhiteboardIndex 与显示信息；还会将左右两侧 ListView 的 SelectedIndex 同步为命中项索引。 
+        /// - 在查找命中或切换过程中发生的异常将被捕获并忽略，不会向上抛出。
+        /// </remarks>
        private void TrySwitchWhiteboardPageByTouchPoint(ListView listView, ScrollViewer scrollViewer, Point pointInScrollViewer)
        {
            if (listView == null || scrollViewer == null) return;
@@ -109,6 +122,12 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 在视觉树中自下而上查找并返回第一个匹配指定类型的祖先元素。
+        /// </summary>
+        /// <typeparam name="T">要查找的祖先类型，必须继承自 <see cref="DependencyObject"/>。</typeparam>
+        /// <param name="current">起始节点；从此节点开始向上遍历视觉树。</param>
+        /// <returns>找到的第一个类型为 <typeparamref name="T"/> 的祖先元素，未找到时返回 <c>null</c>。</returns>
        private static T FindAncestorOfType<T>(DependencyObject current) where T : DependencyObject
        {
            while (current != null)
@@ -119,6 +138,11 @@ namespace Ink_Canvas
            return null;
        }

+        /// <summary>
+        /// 将指定元素在给定 ScrollViewer 中滚动，使该元素与可视区域的顶部对齐。
+        /// </summary>
+        /// <param name="element">要对齐到顶部的元素。</param>
+        /// <param name="scrollViewer">包含该元素的目标 ScrollViewer。</param>
        public static void ScrollViewToVerticalTop(FrameworkElement element, ScrollViewer scrollViewer)
        {
            if (element == null || scrollViewer == null)
@@ -139,6 +163,24 @@ namespace Ink_Canvas
        }


+        /// <summary>
+        /// 左侧页面列表视图的鼠标释放事件处理
+        /// </summary>
+        /// <param name="sender">发送者</param>
+        /// <param name="e">鼠标按钮事件参数</param>
+        /// <remarks>
+        /// 该方法会：
+        /// 1. 隐藏左右侧页面边框
+        /// 2. 获取选中的项目和索引
+        /// 3. 只有当选择的页面与当前页面不同时才进行切换
+        /// 4. 如果有选中的元素，先取消选择
+        /// 5. 保存当前页面的笔画
+        /// 6. 清空画布
+        /// 7. 更新当前白板索引
+        /// 8. 恢复新页面的笔画
+        /// 9. 更新索引信息显示
+        /// 10. 更新选择索引
+        /// </remarks>
        private void BlackBoardLeftSidePageListView_OnMouseUp(object sender, MouseButtonEventArgs e)
        {
            AnimationsHelper.HideWithSlideAndFade(BoardBorderLeftPageListView);
@@ -172,6 +214,24 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 右侧页面列表视图的鼠标释放事件处理
+        /// </summary>
+        /// <param name="sender">发送者</param>
+        /// <param name="e">鼠标按钮事件参数</param>
+        /// <remarks>
+        /// 该方法会：
+        /// 1. 隐藏左右侧页面边框
+        /// 2. 获取选中的项目和索引
+        /// 3. 只有当选择的页面与当前页面不同时才进行切换
+        /// 4. 如果有选中的元素，先取消选择
+        /// 5. 保存当前页面的笔画
+        /// 6. 清空画布
+        /// 7. 更新当前白板索引
+        /// 8. 恢复新页面的笔画
+        /// 9. 更新索引信息显示
+        /// 10. 更新选择索引
+        /// </remarks>
        private void BlackBoardRightSidePageListView_OnMouseUp(object sender, MouseButtonEventArgs e)
        {
            AnimationsHelper.HideWithSlideAndFade(BoardBorderLeftPageListView);
@@ -206,4 +266,4 @@ namespace Ink_Canvas
        }

    }
-}
+}