docs: specify planner documentation alignment

2026-08-09 22:18:30 +08:00
parent 2f4fd15e52
commit 0062602232
1 changed files with 62 additions and 0 deletions
@@ -0,0 +1,62 @@
 # 规划模块 README 与代码注释对齐设计
 ## 目标
 将 `EMPlanner`、`TrajectoryExecution` 与 `tarjplanner_movementtest` 的 README 和 C# 注释统一为 `CoarsePath` 的中文工程文档风格，使调用边界、数据流、单位、安全限制和验证方式可以在不阅读全部实现的情况下被准确理解。
 ## 范围
 - 重构以下 README：
  - `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md`
  - `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md`
  - `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md`
 - 审阅并补充以上三个目录内全部 C# 文件的中文注释。
 - 只修改说明性文字；不改变类型签名、运行逻辑、配置默认值、运行时行为或测试断言。
 ## README 结构
 每份 README 按模块实际能力选择下列章节，沿用 CoarsePath 的中英文标题形式：
 1. 模块定位与唯一推荐调用入口。
 2. 模块说明，明确负责与不负责内容。
 3. 文件结构，逐项对应真实文件和职责。
 4. 数据流，说明上游输入、核心处理、下游输出与禁止的旁路调用。
 5. 状态、失败、取消与停止边界。
 6. 坐标、时间和单位约定。
 7. 最小调用示例与逐步使用指南。
 8. 验证命令、常见错误与首版限制。
 不适用于模块的章节不会伪造。例如，观察型 MovementTest 会重点说明只读边界、会话启动与停止，而不是虚构硬件控制接口。
 ## 模块边界
 ```text
 CoarsePath / PathSmoothing
          │ 已验证的几何路径与方向段
          ▼
 EMPlanner
          │ 横向/纵向优化后的 EmTrajectory
          ▼
 TrajectoryExecution
          │ 与真实状态对齐的通用控制意图
          ▼
 未来硬件适配器（不在本次范围）
 tarjplanner_movementtest
          └── 只读地组合、观察和可视化上述规划结果；绝不发送底盘命令
 ```
 ## 注释规则
 - 为每个类型提供中文 XML 摘要，说明职责、关键输入/输出与模块边界。
 - 为公开属性、构造参数、枚举值和关键方法说明单位、有效范围、可空/失败语义和调用方责任。
 - 在优化、插值、轨迹交接、换向和会话生命周期等核心位置使用简短的中文块注释描述原因与不变量，而不是逐行复述语法。
 - 安全和观察边界使用明确措辞：执行层只生成通用命令；观察模块不驱动、转向、制动或换向。
 - 保留正确且有价值的原有注释；只修正与代码不符、英文混杂或风格不一致的部分。
 ## 验证
 - 以 `rg` 检查 README 中出现的代码路径、公共类型和验证命令均存在。
 - 检查所有目标 C# 文件拥有一致的文件/类型级注释，且关键公共 API 未留下英文占位说明。
 - 运行 `ClumsyPilot/tests/EMPlannerVerificationHost` 的相关既有验证入口；若文档引用的命令与实际项目不符，修正文档而不伪造命令。
 - 运行 `git diff --check`；对既有、与本次无关的格式问题单独报告，不自动改写。