Skip to content

Template_Module_Overview.md

Latest commit

 

History

History
232 lines (159 loc) · 5.93 KB

Template_Module_Overview.md

File metadata and controls

232 lines (159 loc) · 5.93 KB

Template: 模块总览文档（B 类）

文档类型: B — 模块级解析
使用场景: 一个模块（子目录 / 一组相关文件）的整体概要
使用方式: 复制本文件，替换所有 [...] 占位符，删除所有 <!-- 说明: ... --> 注释行

[N.M] [ModuleName] [中文模块名]

源文件:

  • [repo_root]/src/[module]/[main_file].h
  • [repo_root]/src/[module]/[main_file].cc
  • [repo_root]/src/[module]/[helper_file].cc

1. 模块定位

[ModuleName] 是 [所属子系统] 中负责 [核心职责一句话] 的模块。

在 Pipeline 中的位置：

[上游模块/函数] ──输出[数据类型]──▶  [ModuleName]  ──输出[数据类型]──▶ [下游模块/函数]
项目 说明
所属子系统 [Scheduler / Decision / Path / Speed / ...]
核心职责 [一句话]
调用频率 [每帧 / 按需 / 初始化一次]
线程安全 [是 / 否 / 只读]
命名空间 [namespace::name]

2. 文件清单与分工

列出模块内所有文件及其职责，帮助读者快速定位入口

文件 类型 职责
[main_file].h 头文件 公开 API、数据结构声明
[main_file].cc 实现 核心逻辑实现
[helper_file].cc 辅助 [工具函数 / 子算法 / 配置解析]
[data_struct].h 数据结构 [关键数据结构定义]

3. 公开接口

3.1 核心类: [ClassName]

// [main_file].h
class [ClassName] {
 public:
  // 构造 / 初始化
  [ClassName](/* 构造参数 */);

  // 主接口
  [ReturnType] [MainMethod](/* 参数 */);  // [一句话说明]

  // 辅助查询
  [ReturnType] [QueryMethod]() const;     // [一句话说明]
};

3.2 独立函数接口（若有）

// 函数签名（带注释）
[ReturnType] [FunctionName](
    [ParamType] param1,  // [说明]
    [ParamType] param2); // [说明]

4. 关键数据结构

4.1 [StructName]

struct [StructName] {
  [FieldType] field_a;   // [说明，含单位]
  [FieldType] field_b;   // [说明，含单位]
  [FieldType] field_c;   // [说明]
};
字段 类型 单位 说明
field_a [type] [m/s/rad/–] [说明]
field_b [type] [m/s/rad/–] [说明]

5. 核心执行流程

5.1 步骤一：[初始化/准备/入参校验]

[说明这一步做什么，1~2 句]

// [main_file].cc: [ClassName]::[MainMethod]
// 关键代码片段（不要粘贴整个函数）

5.2 步骤二：[核心处理]

[说明这一步做什么，1~2 句]

// 关键代码片段

5.3 步骤三：[结果组装/写出]

[说明这一步做什么，1~2 句]

// 关键代码片段

6. 流程图

flowchart TD
    A["入口: [MainMethod]()"] --> B["步骤一: [初始化]"]
    B --> C{"[关键分支条件]?"}
    C -->|"是"| D["路径 A: [处理逻辑]"]
    C -->|"否"| E["路径 B: [处理逻辑]"]
    D --> F["步骤三: [结果写出]"]
    E --> F
    F --> G["返回 [输出类型]"]
Loading

7. 输入 / 输出协议

输入

参数 / 来源 类型 说明
[param] [type] [来自什么模块，表示什么]
[config] [ProtoName] [配置来源]

输出

输出 / 目标 类型 说明
[output] [type] [流向哪个模块，代表什么]

8. 关键参数说明

参数 来源 默认值 单位 说明
[param_name] [ProtoName/hardcode] [value] [m/s/–] [含义 + 为什么选这个值]

9. 模块间依赖关系

上游调用者:
  [ModuleA]  ──▶  [ModuleName]::MainMethod()

本模块内部依赖:
  [ModuleName] 使用 [SubModule/HelperClass]

下游消费者:
  [ModuleName] 输出 ──▶  [ModuleB]

10. 设计意图与边界条件

  1. 设计意图: [为什么这样设计，解决了什么问题]
  2. 重要边界: [什么情况下行为异常 / 需要特别注意]
  3. 已知限制: [当前实现的局限性，若有]
  4. 改进方向: [可选，若有明显可优化点]

11. 关联文档

方向 文档 关联点
上游 [文档链接] [传入哪个数据结构]
下游 [文档链接] [接收哪个输出]
同层 [文档链接] [协作关系]
算法 [文档链接] [底层算法说明]