# XCEngine API 文档编写与校验 Skill

## 用途

根据 XCEngine C++ 引擎源码生成符合规范的 API 文档，并进行格式校验和查漏补缺。

---

## 文档层次结构规范

### 文件命名

文档文件统一命名为 `{module-name}.md`，按子系统组织目录结构：

```
docs/api/
├── index.md                    # 总索引
├── math/                      # 数学库
├── containers/                 # 容器
├── memory/                     # 内存管理
├── threading/                  # 线程与任务
├── debug/                      # 调试与日志
├── core/                       # 核心基础
├── rhi/                        # RHI 抽象层
│   ├── d3d12/                # D3D12 后端
│   └── opengl/                # OpenGL 后端
└── resources/                  # 资源管理
```

### 文档模板

```markdown
# {类/结构体名称}

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

**类型**: `{type}` (`class` / `struct` / `class` (abstract) / `class` (template) / `class` (singleton) / `enum` / `struct`)

**描述**: {一句话功能描述}

## 概述

{模块功能详细介绍，包括设计目的和使用场景}

## {类型别名/子类型 1}（可选章节）

{子类型详细说明}

## 公共方法

### {方法分组 1}

| 方法 | 描述 |
|------|------|
| `{signature}` | {描述} |

### {方法分组 2}

| 方法 | 描述 |
|------|------|
| `{signature}` | {描述} |

## 公共成员（struct/enum 时）

| 成员 | 类型 | 描述 |
|------|------|------|
| `{name}` | `{type}` | {description} |

## 枚举值（enum 时）

| 值 | 描述 |
|----|------|
| `{EnumValue}` | {description} |

## 使用示例

```cpp
{代码示例}
```

## 相关文档

- [{文档名}](./{filename}.md) - {简短描述}
```

---

## 必需字段规范

### 元信息（必须）

- `**命名空间**`: C++ 命名空间，如 `XCEngine::Math`、`XCEngine::RHI`
- `**类型**`: `class`、`struct`、`enum`、`class` (abstract)、`class` (template)、`class` (singleton)
- `**描述**`: 一句话功能描述

### 必需章节

1. **概述** - 模块功能介绍（设计目的、使用场景）
2. **公共方法** - 所有 public 方法按逻辑分组列出
3. **使用示例** - 完整可运行的代码示例
4. **相关文档** - @see 交叉引用

### 可选章节（按需添加）

- **类型别名/子类型** - 嵌套类型、结构体成员、枚举值
- **构造/析构**
- **运算符重载**
- **静态方法**
- **私有成员说明**

---

## 校验规则

### 1. 格式校验

- [ ] 文档有且只有一个 `#` 一级标题
- [ ] 元信息完整：`命名空间`、`类型`、`描述`
- [ ] 每个方法有清晰的分组标题
- [ ] 代码块使用 ``` 包裹，语言标识正确（`cpp`、`json`）
- [ ] 表格格式正确：`|header|`，有分隔行 `|------|------|`

### 2. 引用校验

- [ ] `@see` / `- [xxx](./xxx.md)` 引用的文件存在
- [ ] 引用路径使用相对路径
- [ ] 不存在循环引用

### 3. 内容校验

- [ ] 所有 public 方法都已列出
- [ ] 方法签名与源码一致
- [ ] 返回值类型正确
- [ ] 默认参数值标注清楚
- [ ] 示例代码可编译运行
- [ ] 命名空间与源码一致

---

## 生成流程

1. **扫描源码**：分析 `engine/include/XCEngine/` 目录下的头文件
2. **识别 API**：查找 `class`、`struct`、`enum`、`namespace`
3. **提取信息**：从源码中提取方法签名、成员变量、枚举值、文档注释
4. **生成文档**：按照上述模板生成 Markdown 文件
5. **校验输出**：运行校验规则，检查格式和引用
6. **输出报告**：列出生成的文档和发现的问题

---

## 各子系统文档清单

### Math 模块

- [x] math-overview.md
- [x] math-h.md (常量)
- [x] math-vector2.md
- [x] math-vector3.md
- [x] math-vector4.md
- [x] math-matrix3.md
- [x] math-matrix4.md
- [x] math-quaternion.md
- [x] math-transform.md
- [x] math-color.md
- [x] math-plane.md
- [x] math-sphere.md
- [x] math-box.md
- [x] math-bounds.md
- [x] math-aabb.md
- [x] math-frustum.md
- [x] math-ray.md
- [x] math-rect.md

### Containers 模块

- [x] container-overview.md
- [x] container-array.md
- [x] container-string.md
- [x] container-hashmap.md

### Memory 模块

- [x] memory-overview.md
- [x] memory-allocator.md
- [x] memory-linear-allocator.md
- [x] memory-pool-allocator.md
- [x] memory-proxy-allocator.md
- [x] memory-manager.md

### Threading 模块

- [x] threading-overview.md
- [x] threading-thread.md
- [x] threading-mutex.md
- [x] threading-spinlock.md
- [x] threading-readwritelock.md
- [x] threading-task.md
- [x] threading-lambdatask.md
- [x] threading-task-group.md
- [x] threading-task-system.md
- [x] threading-tasksystemconfig.md

### Debug 模块

- [x] debug-overview.md
- [x] debug-logger.md
- [x] debug-ilogsink.md
- [x] debug-consolelogsink.md
- [x] debug-filelogsink.md
- [x] debug-loglevel.md
- [x] debug-logcategory.md
- [x] debug-logentry.md
- [x] debug-profiler.md

### Core 模块

- [x] core-overview.md
- [x] core-types.md
- [x] core-smartptr.md
- [x] core-refcounted.md
- [x] core-event.md
- [x] core-filewriter.md

### RHI 模块（抽象层）

- [x] rhi-overview.md
- [x] rhi-device.md
- [x] rhi-factory.md
- [x] rhi-buffer.md
- [x] rhi-texture.md
- [x] rhi-shader.md
- [x] rhi-command-list.md
- [x] rhi-command-queue.md
- [x] rhi-swap-chain.md
- [x] rhi-fence.md
- [x] rhi-pipeline-state.md
- [x] rhi-sampler.md
- [x] rhi-pipeline-layout.md
- [x] rhi-descriptor-pool.md
- [x] rhi-capabilities.md
- [x] rhi-types.md
- [x] rhi-enums.md

### RHI D3D12 后端

- [x] d3d12-overview.md
- [x] d3d12-device.md
- [x] d3d12-buffer.md
- [x] d3d12-texture.md
- [x] d3d12-command-list.md
- [x] d3d12-command-queue.md
- [x] d3d12-swap-chain.md
- [x] d3d12-fence.md
- [x] d3d12-shader.md
- [x] d3d12-pipeline-state.md
- [x] d3d12-sampler.md
- [x] d3d12-root-signature.md
- [x] d3d12-descriptor-heap.md
- [x] d3d12-render-target-view.md
- [x] d3d12-depth-stencil-view.md
- [x] d3d12-shader-resource-view.md
- [x] d3d12-unordered-access-view.md
- [x] d3d12-constant-buffer-view.md
- [x] d3d12-command-allocator.md
- [x] d3d12-query-heap.md
- [x] d3d12-screenshot.md
- [x] d3d12-types.md
- [x] d3d12-enums.md
- [x] d3d12-common.md

### RHI OpenGL 后端

- [x] opengl-overview.md
- [x] opengl-device.md
- [x] opengl-buffer.md
- [x] opengl-texture.md
- [x] opengl-command-list.md
- [x] opengl-command-queue.md
- [x] opengl-swap-chain.md
- [x] opengl-fence.md
- [x] opengl-shader.md
- [x] opengl-pipeline-state.md
- [x] opengl-sampler.md
- [x] opengl-vertex-array.md
- [x] opengl-render-target-view.md
- [x] opengl-depth-stencil-view.md

### Resources 模块

- [x] resources-overview.md
- [x] resources-iresource.md
- [x] resources-resourcehandle.md
- [x] resources-iloader.md
- [x] resources-resourcemanager.md
- [x] resources-resourcecache.md
- [x] resources-asyncloader.md
- [x] resources-dependencygraph.md
- [x] resources-filesystem.md
- [x] resources-resourcetypes.md
- [x] resources-importsettings.md

---

## 输出格式

```json
{
  "generated": [
    {
      "file": "docs/api/math/math-vector3.md",
      "status": "created",
      "classes": 1,
      "methods": 15
    }
  ],
  "issues": [
    {
      "file": "docs/api/rhi/rhi-overview.md",
      "type": "broken_reference",
      "message": "../rhi/d3d12/d3d12-device.md 引用了不存在的文件，应为 ../rhi/d3d12/d3d12-overview.md"
    }
  ]
}
```

---

## 使用示例

用户输入：
```
完善 docs/api 文档，检查并修复错误
```

AI 执行：
1. 扫描 `engine/include/XCEngine/` 源码目录
2. 识别所有头文件中的 class/struct/enum
3. 对比现有文档，找出缺失文件和错误引用
4. 生成或修复 Markdown 文档
5. 运行校验检查格式和引用
6. 输出生成报告和问题列表