# 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. 注意：缓存、坐标转换、不可变性、线程安全或失败语义等调用者必须知道的约束。

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

## 注释示例

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

## 验收

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