docs: design planner comment overhaul

2026-08-04 14:09:42 +08:00
parent 37010cbfad
commit 01b548a0ea
1 changed files with 55 additions and 0 deletions
@@ -0,0 +1,55 @@
+# 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 服务。