XCEngine/docs/api-skill.md

XCEngine API Documentation Skill

目标

本规范用于为 XCEngine 生成和维护一套唯一的 canonical API 文档。

硬性要求：

1. docs/api/XCEngine/** 必须与 engine/include/XCEngine/** 严格平行。
2. 模块、子模块、类型、方法的命名必须稳定并贴近源码符号名。
3. 不保留第二套正式文档树。历史文档只允许作为迁移过程中的临时材料，迁移完成后必须删除。

在编写任何 API 文档之前，必须先阅读对应头文件与相关实现，理解职责、边界、生命周期、线程语义、错误条件和依赖关系。禁止只根据函数名猜测含义。

Canonical 目录结构

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. 目录总览页模板

# {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. 类型总览页模板

# {TypeName}

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

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

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

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

## 概览

{描述该类型的职责、拥有关系、状态约束、典型使用方式}

## 声明概览

| 声明 | 类型 | 说明 |
|------|------|------|
| `{TypeName}` | `class` | {说明} |

## 公共方法

| 方法 | 描述 |
|------|------|
| [Initialize](Initialize.md) | {描述} |
| [Shutdown](Shutdown.md) | {描述} |

## 相关文档

- [当前目录](../{DirName}.md)

3. 方法详情页模板

# {TypeName}::{MethodName}

{一句话说明方法职责}

```cpp
{完整签名}

{方法行为说明，包括前置条件、后置条件、副作用和失败语义}

参数

• param - {描述}

返回

• {Type} - {描述}

线程语义

• {线程安全 / 只能主线程 / 调用方同步等}

示例

{最小可信示例}

相关文档

• 返回类型总览
• 返回模块目录

## 文风与质量要求

- 使用工程化、可审阅、可维护的描述，不写空话
- 描述职责边界，而不是复述函数名
- 线程、生命周期、资源所有权、错误条件必须明确
- 示例必须与当前 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 文档树