57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
|
# 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 的建图算法、缓存键或运行时行为。
|