ParkingRobot/docs/superpowers/specs/2026-07-27-map-documentation-design.md

Map 模块文档与注释设计

目标

让阅读 ClumsyPilot/ParkrobTrajplanner/Map 的开发者无需反查实现，即可理解模块文件职责、建图数据流和所有公共 API 的调用契约。

交付内容

Map/README.md

README 是 Map 模块的入口说明，只保留不会由 IDE 自动展示的模块级信息：

• 当前目录树，以及每个文件的一句话职责；
• 从 PlanningMapRequest 到 PlanningGridMap 的建图数据流；
• 坐标系和单位约定；
• PlanningMapFactory 的最小调用示例；
• 缓存与 SourceVersion 的使用约束；
• 测试、PNG 调试和旧 TrapMap 的边界。

README 不复制逐个参数说明；参数的唯一权威说明位于声明处的代码注释。

.cs 代码注释

覆盖 Map 内所有 public 类、接口、枚举、构造函数、方法和属性。注释使用可被 C# IDE 识别的 /// XML 文档注释，但按 Python docstring 的阅读顺序组织：

1. 功能：该成员做什么；
2. 参数：名称、类型语义、单位、可空性或约束；
3. 返回：返回对象及字段的业务意义；
4. 注意：缓存、坐标转换、不可变性、线程安全或失败语义等调用者必须知道的约束。

不为纯私有实现逐项添加重复注释；复杂算法的私有方法只在其现有说明明显不足、且会妨碍维护时补充最小必要说明。

注释示例

/// <summary>
/// 创建规划地图快照。
///
/// 参数：
/// - request：建图请求，包含世界范围、栅格分辨率和障碍物来源。
///
/// 返回：
/// - PlanningMapBuildResult：成功时含不可变地图、来源投影结果和缓存命中类型。
///
/// 注意：
/// - 应长期复用工厂实例，才能复用缓存。
/// </summary>
public PlanningMapBuildResult Create(PlanningMapRequest request)

验收

• Map/README.md 可独立说明文件结构、数据流和公共入口；
• 通过 rg 检查，所有 Map 公共 API 均有紧邻的中文 /// 文档说明；
• 现有 Map Gate 与项目编译保持通过；
• 不修改 Map 的建图算法、缓存键或运行时行为。