XCEngine/docs/api-skill.md

# XCEngine API Documentation Skill

## 目标

本规范用于维护 `XCEngine` 的唯一正式 API 文档树，并约束后续所有模块级重构的工作方式。

硬性要求：

1. `docs/api/XCEngine/**` 必须与 `engine/include/XCEngine/**` 保持平行。
2. canonical API 文档只保留一套；迁移完成后必须删除旧目录与旧入口。
3. 默认情况下，每个 public header 对应一个独立文档目录，每个类型页都使用 `{TypeName}/{TypeName}.md`。
4. 方法页优先使用源码中的原始函数名；不要改成 kebab-case、全小写或其它再命名形式。
5. API 文档必须以源码、实现、测试和真实调用点为依据，禁止只根据名字猜测行为。
6. 对于只承担聚合包含职责的 umbrella header，可以并入模块页说明，不强制再建一个同名类型目录。

## Canonical 目录结构

```text
docs/api/
├── main.md
├── XCEngine/
│   ├── XCEngine.md
│   ├── Debug/
│   │   ├── Debug.md
│   │   ├── Logger/
│   │   │   ├── Logger.md
│   │   │   ├── Get.md
│   │   │   ├── Initialize.md
│   │   │   └── Log.md
│   │   └── RenderDocCapture/
│   │       ├── RenderDocCapture.md
│   │       └── BeginCapture.md
│   └── ...
├── _guides/
│   └── Debug/
└── _meta/
```

说明：

- `docs/api/XCEngine/**` 是唯一 canonical API 树。
- `docs/api/_guides/**` 用于概念、教程、设计理念和工作流说明，不是第二套 API 树。
- `README.md` 不用于 canonical 模块索引页；模块索引页统一使用 `{DirName}.md`。

## 强制命名规则

### 1. 目录索引页

- 根索引页：`docs/api/XCEngine/XCEngine.md`
- 模块索引页：`docs/api/XCEngine/{ModuleName}/{ModuleName}.md`
- 子模块索引页：`docs/api/XCEngine/{ModuleName}/{SubmoduleName}/{SubmoduleName}.md`

示例：

- `docs/api/XCEngine/Debug/Debug.md`
- `docs/api/XCEngine/Core/Core.md`
- `docs/api/XCEngine/RHI/D3D12/D3D12.md`

### 2. 类型目录

- 每个 public header 对应一个独立文件夹。
- 文件夹名必须与 header stem 或主要类型名一致。
- 保留源码中的大小写，不做风格改写。
- 如果 header 只是模块聚合入口，不声明独立类型，可以直接并入模块页，不单独建文件夹。

示例：

- `docs/api/XCEngine/Debug/Logger/`
- `docs/api/XCEngine/Core/Asset/ResourceManager/`
- `docs/api/XCEngine/RHI/D3D12/D3D12Device/`

### 3. 类型总览页

- 固定为 `{TypeName}/{TypeName}.md`
- 不允许把类型总览页直接平铺在模块目录中

### 4. 方法详情页

- 方法页放在所属类型目录内。
- 文件名优先使用原函数名。
- 重载共享同一页，在页内按签名分节说明。

示例：

- `Get.md`
- `Initialize.md`
- `SetCaptureFilePath.md`
- `LoadSceneAsync.md`

### 5. 特殊命名

- 构造函数：`Constructor.md`
- 析构函数：`Destructor.md`
- 运算符使用可读的 PascalCase 名称

建议映射：

- `operator=` -> `OperatorAssign.md`
- `operator+=` -> `OperatorPlusAssign.md`
- `operator[]` -> `OperatorSubscript.md`
- `operator()` -> `OperatorCall.md`

## 写作前的取证流程

在编写任何 API 页之前，必须完成下面的最小取证：

1. 阅读对应 public header。
2. 阅读对应 `.cpp` 或内联实现。
3. 搜索测试、示例和真实调用点。
4. 确认生命周期、线程语义、所有权、失败路径和平台限制。

至少回答以下问题后才能落文：

- 这个类型解决什么问题，边界在哪里？
- 调用前需要什么前置条件？
- 调用失败时返回什么，或者会静默失败？
- 谁拥有对象，谁负责释放资源？
- 多线程下哪些调用安全，哪些只能在初始化阶段使用？
- 当前实现是不是完整的？有没有空实现、占位实现或只做轻量封装？

禁止行为：

- 只根据 `Get`、`Create`、`Set` 之类的前缀写模板句。
- 把“设计意图”当成“当前实现行为”来写。
- 把测试里假设成立的场景，误写成通用保证。

## umbrella header 例外规则

以下情况通常应视为模块聚合头，而不是单独类型页：

- 头文件主要由一组 `#include` 组成。
- 不声明独立类、结构体、枚举或函数族。
- 名称与模块目录同名，单独建页会造成 `Debug/Debug.md` 这类重复入口。

处理方式：

- 在模块页中增加“聚合头文件”或“包含入口”小节。
- 使用 `**头文件**: \`...\`` 保留头文件覆盖记录。
- 不再额外创建 `{HeaderStem}/{HeaderStem}.md`。

## 契约分层规则

文档必须明确区分下面三层信息：

### 1. 接口契约

来自 public header，属于使用者可以依赖的 API 形状。

例如：

- 函数签名
- 参数和返回值
- 可见的数据结构
- 明确暴露的枚举值和宏

### 2. 当前实现行为

来自 `.cpp`、内联实现、测试和调用点，描述当前版本的真实行为。

例如：

- 是否自动初始化
- 是否加锁
- 是否会写日志、刷新文件、拉起窗口焦点
- 是否只是 no-op 或 stub

这一层必须使用明确表述，例如：

- “当前实现中……”
- “按 `engine/src/...` 的实现……”
- “当前版本会……”

### 3. 合理推断

只在确实有必要时使用，而且必须标明是推断。

例如：

- “从 API 形状看，设计上显然是为后续 Chrome Trace 导出预留扩展点。”

如果不能证明，就不要写。

## 页面职责

### 1. 模块页 / 子模块页

负责：

- 说明模块职责、边界和典型使用场景
- 列出子目录与 public headers
- 给出与相邻模块的关系
- 链接相关 guide 页

不负责：

- 展开所有方法细节
- 重复 header 全量声明

### 2. 类型页

必须包含：

- 命名空间
- 类型分类
- 头文件
- 角色概述
- 生命周期
- 线程语义
- 所有权 / 资源管理方式
- 当前实现限制
- 与相关方法页、guide 页的跳转

如果类型是枚举或结构体，还应补充：

- 字段或枚举值说明
- 值之间的语义关系
- 典型使用方式

### 3. 方法页

必须包含：

- 准确签名
- 调用目的
- 前置条件
- 参数说明
- 返回值说明
- 副作用
- 线程语义
- 失败路径或 no-op 条件
- 最小可信示例

方法页不能只写“获取对象”“设置状态”这种空描述。

## 内容深度要求

### 1. 解释“是什么”

说明类型或方法的职责，而不是简单复述名字。

### 2. 解释“怎么用”

给出最小可运行或最小可信的使用顺序，让用户知道放在初始化、运行时还是销毁阶段。

### 3. 解释“为什么这样设计”

结合引擎架构解释：

- 为什么做成 singleton、service、interface、sink、builder、handle
- 这样做的收益是什么
- 有哪些代价或约束

### 4. 解释“当前实现做到哪一步”

商业级 API 文档不能假装所有接口都同样成熟。

对于未完成能力，必须明确说明：

- 当前是占位接口
- 当前只有基础实现
- 当前只覆盖某个平台 / 某条后端路径

## 教程与概念页规范

当某个模块仅靠 API 页不足以让用户理解时，应增加 `_guides` 页。

适合写 guide 的内容：

- 前置知识
- 架构设计理念
- 推荐工作流
- 和 Unity / Unreal / RenderDoc 等常见工具的概念对照
- 最佳实践与反模式

guide 页不是第二套 API 参考，它们负责回答：

- 为什么要这样组织模块
- 用户第一次接触时该从哪里开始
- 这套 API 与常见引擎的对应关系是什么

guide 页应尽量包含：

- 问题背景
- 设计目标
- 推荐流程
- 优点与代价
- 与现有 API 页的链接

## Unity 风格的解释性要求

当模块涉及常见引擎概念时，可以增加 Unity 对照，但必须克制且准确。

推荐写法：

- “可以把 `Logger` 理解为比 Unity Console 更底层的日志分发中心。”
- “当前 `Profiler` 只覆盖轻量 CPU 埋点，不等同于 Unity Profiler 的完整时间线分析。”
- “`RenderDocCapture` 更接近引擎内置的 RenderDoc 工作流桥接，而不是 Unity Frame Debugger 的替代品。”

禁止写法：

- “和 Unity 完全一样”
- “等价于某商业引擎的完整系统”

## 页面模板

### 1. 模块页模板

```markdown
# {DirName}

**命名空间**: `{Namespace}`

**类型**: `module` / `submodule` / `module-root`

**描述**: {一句话说明当前目录职责}

## 概述

{解释职责边界、典型场景和相邻模块关系}

## 设计要点

- {要点 1}
- {要点 2}

## 头文件

- [TypeA](TypeA/TypeA.md) - `TypeA.h`
- [TypeB](TypeB/TypeB.md) - `TypeB.h`

## 相关指南

- [GuideA](../../_guides/.../GuideA.md)
```

### 2. 类型页模板

```markdown
# {TypeName}

**命名空间**: `{Namespace}`

**类型**: `class` / `class (abstract)` / `class (singleton)` / `struct` / `enum class`

**头文件**: `XCEngine/.../{Header}.h`

**描述**: {一句话说明}

## 概述

{说明角色、状态、边界、典型使用方式}

## 生命周期

- {初始化与销毁方式}

## 线程语义

- {线程安全说明}

## 公开成员

| 成员 | 说明 |
|------|------|
| [Initialize](Initialize.md) | {说明} |
| [Shutdown](Shutdown.md) | {说明} |
```

### 3. 方法页模板

```markdown
# {TypeName}::{MethodName}

{一句话说明方法职责}

```cpp
{完整签名}
```

## 行为说明

{说明前置条件、后置状态、副作用和当前实现细节}

## 参数

- `param` - {描述}

## 返回值

- `{Type}` - {描述}

## 线程语义

- {线程安全、只建议初始化阶段调用、或必须同线程配对等}

## 示例

```cpp
{最小可信示例}
```
```

## 验收清单

- `docs/api/XCEngine/**` 与 `engine/include/XCEngine/**` 目录平行
- canonical 树下没有模块级 `README.md`
- 每个 public header 都有对应类型目录
- 每个类型总览页都位于 `{TypeName}/{TypeName}.md`
- 方法页使用原函数名或规范化运算符名
- 所有链接都指向真实存在的 `.md` 页面
- 文档中明确区分接口契约、当前实现和合理推断
- 重要模块拥有必要的 guide 页
- 重要限制、stub、平台条件和线程语义都已写清