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
@@ -8,11 +8,20 @@ namespace Ink_Canvas.Windows.SettingsViews
 {
    public partial class SecurityPanel : SettingsPanelBase
    {
+        /// <summary>
+        /// 初始化 SecurityPanel 实例并构建其界面组件。
+        /// </summary>
        public SecurityPanel()
        {
            InitializeComponent();
        }

+        /// <summary>
+        /// 从 MainWindow.Settings 将安全相关设置加载并同步到面板的开关控件上。
+        /// </summary>
+        /// <remarks>
+        /// 确保 MainWindow.Settings.Security 存在（若为 null 则创建），在加载期间暂时禁用变更处理以避免触发回调，设置各个开关的状态并更新与密码相关的 UI 状态；任何加载期间的异常会被捕获并静默忽略。
+        /// </remarks>
        public override void LoadSettings()
        {
            if (MainWindow.Settings == null) return;
@@ -37,6 +46,14 @@ namespace Ink_Canvas.Windows.SettingsViews
            _isLoaded = true;
        }

+        /// <summary>
+        /// 更新与主密码相关的界面控件的可用性：根据当前设置启用或禁用“设置/更改密码”按钮及相关用途开关。
+        /// </summary>
+        /// <remarks>
+        /// 当全局安全设置的 PasswordEnabled 为 true 时，启用 BtnSetOrChangePassword 以及以下用途开关：
+        /// ToggleSwitchRequirePasswordOnExit、ToggleSwitchRequirePasswordOnEnterSettings、ToggleSwitchRequirePasswordOnResetConfig；
+        /// 否则禁用它们以阻止操作。
+        /// </remarks>
        private void UpdatePasswordUiState()
        {
            var sec = MainWindow.Settings?.Security;
@@ -54,6 +71,14 @@ namespace Ink_Canvas.Windows.SettingsViews
            if (t3 != null) t3.IsEnabled = usageEnabled;
        }

+        /// <summary>
+        /// 根据切换项标识更新对应的安全设置并保存变更。
+        /// </summary>
+        /// <remarks>
+        /// 对于启用或禁用主密码会在必要时弹出密码设置或验证对话框；对进程保护的修改会同时应用到 ProcessProtectionManager。方法会在成功变更后持久化设置并更新相关 UI 状态，若用户在交互中取消，则会恢复切换控件到原始状态。
+        /// </remarks>
+        /// <param name="tag">切换项的标识字符串，支持的值：`"PasswordEnabled"`、`"RequirePasswordOnExit"`、`"RequirePasswordOnEnterSettings"`、`"RequirePasswordOnResetConfig"`、`"EnableProcessProtection"`。</param>
+        /// <param name="newState">切换的新布尔状态：`true` 表示启用，`false` 表示禁用。</param>
        protected override async void HandleToggleSwitchChange(string tag, bool newState)
        {
            if (MainWindow.Settings == null) return;
@@ -127,16 +152,27 @@ namespace Ink_Canvas.Windows.SettingsViews
            }
        }

+        /// <summary>
+        /// 处理选项按钮组的选择更改。此面板不包含选项按钮组，因此不会执行任何操作。
+        /// </summary>
+        /// <param name="group">选项组的标识（未使用）。</param>
+        /// <param name="value">被选中的值（未使用）。</param>
        protected override void HandleOptionChange(string group, string value)
        {
            // 本面板无选项按钮组
        }

+        /// <summary>
+        /// 处理切换开关的点击事件。
+        /// </summary>
        protected override void ToggleSwitch_Click(object sender, RoutedEventArgs e)
        {
            base.ToggleSwitch_Click(sender, e);
        }

+        /// <summary>
+        /// 向用户弹出设置或更改密码的对话框；当用户输入非空新密码时，将该密码保存到设置中、启用密码功能、持久化设置并更新密码相关的 UI 状态。
+        /// </summary>
        private async void BtnSetOrChangePassword_Click(object sender, RoutedEventArgs e)
        {
            if (MainWindow.Settings == null) return;
@@ -157,6 +193,11 @@ namespace Ink_Canvas.Windows.SettingsViews
        public event EventHandler<RoutedEventArgs> IsTopBarNeedShadowEffect;
        public event EventHandler<RoutedEventArgs> IsTopBarNeedNoShadowEffect;

+        /// <summary>
+        /// 根据 ScrollViewer 的垂直滚动偏移触发顶部栏阴影显示或隐藏事件。
+        /// </summary>
+        /// <param name="sender">触发事件的 ScrollViewer 控件。</param>
+        /// <param name="e">滚动更改的事件参数（未被方法使用）。</param>
        private void ScrollViewerEx_ScrollChanged(object sender, ScrollChangedEventArgs e)
        {
            var scrollViewer = (ScrollViewer)sender;
@@ -164,6 +205,12 @@ namespace Ink_Canvas.Windows.SettingsViews
            else IsTopBarNeedNoShadowEffect?.Invoke(this, new RoutedEventArgs());
        }

+        /// <summary>
+        /// 将当前主题应用到此面板并重新加载面板设置。
+        /// </summary>
+        /// <remarks>
+        /// 在应用主题或重载设置时抛出的异常会被捕获并忽略，不会向上抛出。
+        /// </remarks>
        public void ApplyTheme()
        {
            try
@@ -175,4 +222,3 @@ namespace Ink_Canvas.Windows.SettingsViews
        }
    }
 }
-
@@ -20,6 +20,12 @@ namespace Ink_Canvas.Windows.SettingsViews
            Loaded += SettingsPanelBase_Loaded;
        }

+        /// <summary>
+        /// 处理控件的 Loaded 事件：加载面板设置、启用触摸支持，尝试调用面板的 ApplyTheme 方法（若存在），
+        /// 再次加载设置并将内部已加载标志设为 true。
+        /// </summary>
+        /// <param name="sender">触发事件的对象（通常是当前面板实例）。</param>
+        /// <param name="e">事件参数，包含路由事件的相关信息。</param>
        private void SettingsPanelBase_Loaded(object sender, RoutedEventArgs e)
        {
            LoadSettings();
@@ -272,4 +278,3 @@ namespace Ink_Canvas.Windows.SettingsViews
        protected abstract void HandleOptionChange(string group, string value);
    }
 }
-