# 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 文档树