PathSmoothing 与 TrajectoryExecution 注释设计

目标

将 PathSmoothing 和 TrajectoryExecution 的生产规划核心 XML 文档注释提升至 CoarsePath 的可交接标准：读者无需进入实现，即可了解类型职责、参数类型与语义、单位、返回值、失败语义、快照所有权和安全边界。

本次只修改注释；不改变 C# 签名、控制流、数值算法、测试、项目文件、UI、硬件集成、报告导出或可视化行为。

覆盖范围

PathSmoothing 覆盖以下生产目录：

Contracts/：请求、结果、状态、配置、点、段、诊断和区域报告；
Facade/：平滑服务和比较服务的公开边界；
Processing/：预处理、重采样、几何分析和路径准备的公开或跨目录入口；
Validation/：平滑路径验证入口；
LocalG2/：跨阶段的内部算法入口及其输入/输出 DTO。

明确排除 PathSmoothing/Test/、PathSmoothing/Output/Comparison/、PathSmoothing/Output/Visualization/ 以及报告生成辅助代码。

TrajectoryExecution 覆盖目录中的全部生产文件：周期身份、周期输入/结果、协调器、观察器、状态快照契约、交接选择器、采样器、执行状态、换向状态机、控制适配器和控制命令。

注释规范

类型与属性

每个公开类、接口、枚举及其业务关键属性使用 <summary>，说明：

该类型或属性的职责和数据类型语义；
几何/运动数值的单位（m、rad、1/m、m/s、s）和方向约定；
不可变快照、可空性、集合顺序或所有权；
与调用方、规划器、执行器、UI/硬件之间的边界。

构造函数与方法

构造函数、所有公开方法和关键跨目录内部方法使用 <summary>。有参数时逐项使用 <param name="...">，描述类型角色、单位、有效范围、输入/输出/取消或回退语义；有返回值时使用 <returns>，明确结果类型、成功含义、失败含义和是否允许部分结果。

Try... 方法必须说明 true、false 和每个 out 参数。异步协调方法说明 caller-clocked 时间、取消、latest-wins 发布和线程安全语义。换向/控制方法说明零速、方向确认和通用命令限制。

注释使用中文，与 CoarsePath 风格一致；术语保留现有 C# 类型名和物理单位，不新增不准确的行为承诺。

分层原则

公开 API 获得完整“功能 + 参数 + 返回”文档。内部类型只为算法阶段边界、跨目录协作对象和非显而易见的数学/安全不变量补充文档；不为私有单行工具函数和测试/报告实现增加噪声。

验证

实施时先记录缺失注释的 RED 基线。完成后用 PowerShell 检查目标公开成员以及关键内部入口是否具有 XML 文档块，并检查带参数的方法的 <param>、非 void 方法的 <returns>。使用 git diff --check 确认仅为注释变化；运行现有 PathSmoothing 验证和 em-all，确认注释改动未影响构建或回归。

明确排除

不改变任何功能、算法、数值参数、异常和返回状态；
不修改 PathSmoothing 的测试、比较/可视化/报告导出模块；
不实现动态障碍物、UI、定位、硬件适配、横移、蟹行或原地旋转；
不将执行层外部状态读取注入纯 EM Planner 服务。

3.3 KiB Raw Blame History