From 47eed54ea6f13a627e003191ca5909f516d8ae93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= Date: Sun, 9 Aug 2026 23:50:01 +0800 Subject: [PATCH] docs: require private helper documentation --- .../2026-08-09-planner-readme-comment-alignment-design.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/superpowers/specs/2026-08-09-planner-readme-comment-alignment-design.md b/docs/superpowers/specs/2026-08-09-planner-readme-comment-alignment-design.md index 29f6a9b..ff3eb85 100644 --- a/docs/superpowers/specs/2026-08-09-planner-readme-comment-alignment-design.md +++ b/docs/superpowers/specs/2026-08-09-planner-readme-comment-alignment-design.md @@ -10,7 +10,7 @@ - `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md` - `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md` - `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md` -- 审阅并补充以上三个目录内全部 C# 文件的中文注释。 +- 审阅并补充以上三个目录内全部 C# 文件的中文注释，覆盖类型、构造函数、公开成员、内部成员和每个私有辅助方法。 - 只修改说明性文字；不改变类型签名、运行逻辑、配置默认值、运行时行为或测试断言。 ## README 结构 @@ -49,7 +49,8 @@ tarjplanner_movementtest ## 注释规则 - 为每个类型提供中文 XML 摘要，说明职责、关键输入/输出与模块边界。 -- 为公开属性、构造参数、枚举值和关键方法说明单位、有效范围、可空/失败语义和调用方责任。 +- 为每个构造函数、公开/内部成员及私有辅助方法提供中文 XML 摘要；方法摘要必须说明动作、参数/返回或 `out` 结果、单位（适用时）和失败语义。对重载方法须说明各自适用场景。 +- 为配置属性、构造参数、枚举值和数据契约成员说明单位、有效范围、可空/失败语义和调用方责任；配置项还须说明默认值（若由 `CreateDefault` 提供）。 - 在优化、插值、轨迹交接、换向和会话生命周期等核心位置使用简短的中文块注释描述原因与不变量，而不是逐行复述语法。 - 安全和观察边界使用明确措辞：执行层只生成通用命令；观察模块不驱动、转向、制动或换向。 - 保留正确且有价值的原有注释；只修正与代码不符、英文混杂或风格不一致的部分。 @@ -57,6 +58,6 @@ tarjplanner_movementtest ## 验证 - 以 `rg` 检查 README 中出现的代码路径、公共类型和验证命令均存在。 -- 检查所有目标 C# 文件拥有一致的文件/类型级注释，且关键公共 API 未留下英文占位说明。 +- 检查所有目标 C# 文件拥有一致的文件/类型级注释，且关键公共 API、内部 API 与私有辅助方法均未留下无说明或英文占位说明。 - 运行 `ClumsyPilot/tests/EMPlannerVerificationHost` 的相关既有验证入口；若文档引用的命令与实际项目不符，修正文档而不伪造命令。 - 运行 `git diff --check`；对既有、与本次无关的格式问题单独报告，不自动改写。