278 lines
6.9 KiB
Markdown
278 lines
6.9 KiB
Markdown
# XCEngine API Documentation Skill
|
|
|
|
## 目标
|
|
|
|
本规范用于为 `XCEngine` 生成和维护一套唯一的 canonical API 文档。
|
|
|
|
硬性要求：
|
|
|
|
1. `docs/api/XCEngine/**` 必须与 `engine/include/XCEngine/**` 严格平行。
|
|
2. 模块、子模块、类型、方法的命名必须稳定并贴近源码符号名。
|
|
3. 不保留第二套正式文档树。历史文档只允许作为迁移过程中的临时材料，迁移完成后必须删除。
|
|
|
|
在编写任何 API 文档之前，必须先阅读对应头文件与相关实现，理解职责、边界、生命周期、线程语义、错误条件和依赖关系。禁止只根据函数名猜测含义。
|
|
|
|
## Canonical 目录结构
|
|
|
|
```text
|
|
docs/api/
|
|
├── main.md
|
|
├── XCEngine/
|
|
│ ├── XCEngine.md
|
|
│ ├── Debug/
|
|
│ │ ├── Debug.md
|
|
│ │ ├── Logger/
|
|
│ │ │ ├── Logger.md
|
|
│ │ │ ├── Log.md
|
|
│ │ │ ├── SetLevel.md
|
|
│ │ │ ├── Constructor.md
|
|
│ │ │ └── Destructor.md
|
|
│ │ └── RenderDocCapture/
|
|
│ │ ├── RenderDocCapture.md
|
|
│ │ └── TriggerCapture.md
|
|
│ ├── Core/
|
|
│ │ ├── Core.md
|
|
│ │ ├── Asset/
|
|
│ │ │ ├── Asset.md
|
|
│ │ │ └── ResourceManager/
|
|
│ │ │ ├── ResourceManager.md
|
|
│ │ │ └── Load.md
|
|
│ │ └── Math/
|
|
│ │ └── Math.md
|
|
│ └── ...
|
|
├── _meta/
|
|
└── _tools/
|
|
```
|
|
|
|
## 强制命名规则
|
|
|
|
### 1. 目录总览页
|
|
|
|
- 根目录总览页必须是 `docs/api/XCEngine/XCEngine.md`
|
|
- 模块总览页必须使用 `{ModuleName}.md`
|
|
- 子模块总览页必须使用 `{SubmoduleName}.md`
|
|
- canonical 目录下禁止使用 `README.md` 作为模块或子模块总览页
|
|
|
|
示例：
|
|
|
|
- `docs/api/XCEngine/Debug/Debug.md`
|
|
- `docs/api/XCEngine/Core/Core.md`
|
|
- `docs/api/XCEngine/Core/Asset/Asset.md`
|
|
- `docs/api/XCEngine/RHI/D3D12/D3D12.md`
|
|
|
|
### 2. 类型目录
|
|
|
|
- 每个 public 类型或以 header 为单位的主声明，都必须是一个独立文件夹
|
|
- 文件夹名必须与源码中的类型名或 header stem 保持一致
|
|
- 保留原始大小写
|
|
|
|
示例：
|
|
|
|
- `docs/api/XCEngine/Debug/Logger/`
|
|
- `docs/api/XCEngine/Core/Asset/ResourceManager/`
|
|
- `docs/api/XCEngine/RHI/D3D12/D3D12Device/`
|
|
|
|
### 3. 类型总览页
|
|
|
|
- 类型总览页固定为 `{TypeName}/{TypeName}.md`
|
|
- 不允许把类型总览页直接平铺在模块目录下
|
|
|
|
### 4. 方法详情页
|
|
|
|
- 方法详情页必须放在所属类型文件夹内
|
|
- 方法页文件名优先使用原函数名
|
|
- 保留 PascalCase / camelCase / 全大写缩写
|
|
- 禁止改成 lowercase kebab-case
|
|
- 同名重载共用一个方法页
|
|
|
|
示例：
|
|
|
|
- `Get.md`
|
|
- `CreateBuffer.md`
|
|
- `SetRenderTarget.md`
|
|
- `LoadSceneAsync.md`
|
|
- `GetCPUHandle.md`
|
|
|
|
### 5. 特殊方法命名
|
|
|
|
- 构造函数使用 `Constructor.md`
|
|
- 析构函数使用 `Destructor.md`
|
|
- 运算符重载使用可读的 PascalCase 名称
|
|
|
|
推荐映射：
|
|
|
|
- `operator=` -> `OperatorAssign.md`
|
|
- `operator+=` -> `OperatorPlusAssign.md`
|
|
- `operator[]` -> `OperatorSubscript.md`
|
|
- `operator()` -> `OperatorCall.md`
|
|
- `operator bool` -> `OperatorBool.md`
|
|
|
|
## 页面职责
|
|
|
|
### 1. 目录总览页
|
|
|
|
负责：
|
|
|
|
- 说明模块或子模块的职责边界
|
|
- 列出直接子目录
|
|
- 列出当前目录下的 public headers 对应类型入口
|
|
- 提供父级目录和 `docs/api/main.md` 的导航
|
|
|
|
不负责：
|
|
|
|
- 展开详细方法级说明
|
|
- 复制头文件全部声明
|
|
- 保留迁移说明、旧入口跳转或双轨文档提示
|
|
|
|
### 2. 类型总览页
|
|
|
|
负责：
|
|
|
|
- 标识命名空间、类型、头文件、职责
|
|
- 给出声明概览
|
|
- 列出公开字段、枚举值或公开方法
|
|
- 作为该类型所有方法详情页的稳定入口
|
|
|
|
### 3. 方法详情页
|
|
|
|
负责：
|
|
|
|
- 给出准确签名
|
|
- 按重载分节
|
|
- 说明参数、返回值、生命周期、线程语义和关键约束
|
|
- 给出最小但可信的示例
|
|
|
|
## 推荐页面模板
|
|
|
|
### 1. 目录总览页模板
|
|
|
|
```markdown
|
|
# {DirName}
|
|
|
|
**命名空间**: `{Namespace}`
|
|
|
|
**类型**: `module` / `submodule` / `module-root`
|
|
|
|
**描述**: {一句话说明当前目录职责}
|
|
|
|
## 概览
|
|
|
|
{说明该目录在整个引擎中的职责边界、使用场景和与相邻模块的关系}
|
|
|
|
## 子目录
|
|
|
|
- [ChildA](ChildA/ChildA.md)
|
|
- [ChildB](ChildB/ChildB.md)
|
|
|
|
## 头文件
|
|
|
|
- [TypeA](TypeA/TypeA.md) - `TypeA.h`
|
|
- [TypeB](TypeB/TypeB.md) - `TypeB.h`
|
|
|
|
## 相关文档
|
|
|
|
- [上级目录](../{ParentDir}.md)
|
|
- [API 总索引](../../main.md)
|
|
```
|
|
|
|
### 2. 类型总览页模板
|
|
|
|
```markdown
|
|
# {TypeName}
|
|
|
|
**命名空间**: `{Namespace}`
|
|
|
|
**类型**: `class` / `class (abstract)` / `class (singleton)` / `struct` / `enum class`
|
|
|
|
**头文件**: `XCEngine/.../{Header}.h`
|
|
|
|
**描述**: {一句话说明}
|
|
|
|
## 概览
|
|
|
|
{描述该类型的职责、拥有关系、状态约束、典型使用方式}
|
|
|
|
## 声明概览
|
|
|
|
| 声明 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `{TypeName}` | `class` | {说明} |
|
|
|
|
## 公共方法
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [Initialize](Initialize.md) | {描述} |
|
|
| [Shutdown](Shutdown.md) | {描述} |
|
|
|
|
## 相关文档
|
|
|
|
- [当前目录](../{DirName}.md)
|
|
```
|
|
|
|
### 3. 方法详情页模板
|
|
|
|
```markdown
|
|
# {TypeName}::{MethodName}
|
|
|
|
{一句话说明方法职责}
|
|
|
|
```cpp
|
|
{完整签名}
|
|
```
|
|
|
|
{方法行为说明，包括前置条件、后置条件、副作用和失败语义}
|
|
|
|
**参数**
|
|
- `param` - {描述}
|
|
|
|
**返回**
|
|
- `{Type}` - {描述}
|
|
|
|
**线程语义**
|
|
- {线程安全 / 只能主线程 / 调用方同步等}
|
|
|
|
**示例**
|
|
|
|
```cpp
|
|
{最小可信示例}
|
|
```
|
|
|
|
## 相关文档
|
|
|
|
- [返回类型总览]({TypeName}.md)
|
|
- [返回模块目录](../{DirName}.md)
|
|
```
|
|
|
|
## 文风与质量要求
|
|
|
|
- 使用工程化、可审阅、可维护的描述，不写空话
|
|
- 描述职责边界，而不是复述函数名
|
|
- 线程、生命周期、资源所有权、错误条件必须明确
|
|
- 示例必须与当前 public API 一致，不允许伪代码式胡写
|
|
- 信息应放在正确层级，避免模块页和类型页职责混淆
|
|
- 禁止生成双轨入口或保留旧目录跳转
|
|
|
|
## 重构与生成流程
|
|
|
|
1. 扫描 `engine/include/XCEngine/**`
|
|
2. 建立与源码平行的 `docs/api/XCEngine/**` 目录树
|
|
3. 为每个源码目录生成 `{DirName}.md` 目录总览页
|
|
4. 为每个 public header 生成 `{TypeName}/{TypeName}.md`
|
|
5. 为每个公开方法生成 `{TypeName}/{MethodName}.md`
|
|
6. 清理旧的 lowercase kebab-case 方法页和旧的 flat header 页面
|
|
7. 删除迁移完成后的历史文档
|
|
8. 审计链接、头文件引用覆盖率和目录索引完整性
|
|
|
|
## 验收清单
|
|
|
|
- `docs/api/XCEngine/**` 与 `engine/include/XCEngine/**` 目录结构平行
|
|
- canonical 目录下没有模块级 `README.md`
|
|
- 每个类型都是一个独立文件夹
|
|
- 每个类型总览页都是 `{TypeName}/{TypeName}.md`
|
|
- 方法页文件名使用原函数名或规范化运算符名
|
|
- `docs/api/main.md` 指向 `docs/api/XCEngine/XCEngine.md`
|
|
- 所有 canonical `.md` 链接可解析
|
|
- 所有 public headers 都有对应 canonical 文档入口
|
|
- 仓库中不存在第二套正式 API 文档树
|