# 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 服务。
