XCEngine/skills/doc-api-manager/SKILL.md

XCEngine API 文档编写与校验 Skill

用途

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

---

文档层次结构规范

目录结构

每个类对应一个文件夹，类文件夹下包含类总览页和方法详情页：

docs/api/
├── index.md                     # 总索引
├── math/
│   ├── math.md                  # Math 模块总览
│   ├── vector3.md               # Vector3 类总览
│   ├── dot.md                   # Dot 方法详情
│   ├── cross.md                 # Cross 方法详情
│   └── ...
├── containers/
│   ├── containers.md            # Containers 模块总览
│   ├── array.md                 # Array 类总览
│   ├── emplace.md               # Emplace 方法详情
│   ├── push.md                  # Push 方法详情
│   └── ...
└── ...

规则：

• 模块总览页：{module}/{module}.md（如 math/math.md、containers/containers.md）
• 类文件夹：{class-name}/（如 array/、vector3/）
• 类总览页：{class-name}/{class-name}.md（如 array/array.md）
• 方法详情页：{class-name}/{method-name}.md（如 array/emplace.md）

类总览页模板

# {类名称}

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

**类型**: `{type}`

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

## 概述

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

## 公共方法

| 方法 | 描述 |
|------|------|
| [`Emplace`](./emplace.md) | 原地构造元素 |
| [`Push`](./push.md) | 末尾添加元素 |

## 使用示例

```cpp
{代码示例}

相关文档

• {文档名} - {简短描述}

### 方法详情页模板

```markdown
# {类名称}::{方法名}

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

{方法详细描述，包括设计目的、使用场景、注意事项}

参数：

• {param} - {参数描述}

返回： {返回值描述}

异常： （如有）

线程安全： ✅ / ❌

复杂度： O(n)

示例：

{可运行的完整示例代码}

相关文档

• {类总览} - 返回类总览

---

## 必需字段规范

### 元信息（必须）

- `**命名空间**`: C++ 命名空间，如 `XCEngine::Math`
- `**类型**`: `class`、`struct`、`enum` 等
- `**描述**`: 一句话功能描述

### 必需章节

1. **概述** - 模块功能介绍（设计目的、使用场景）
2. **公共方法** - 表格形式，每个方法链接到详情页
3. **使用示例** - 完整可运行的代码示例
4. **相关文档** - 交叉引用

### 方法详情页必需章节

1. **方法签名** - 完整 C++ 签名
2. **详细描述** - 语义、使用场景、注意事项
3. **参数列表** - 每个参数的含义
4. **返回值** - 返回值含义
5. **示例代码** - 可运行的完整示例
6. **相关文档** - 返回类总览的链接

---

## 校验规则

### 1. 格式校验

- [ ] 文档结构正确：模块有 `{module}/{module}.md`，类有 `{class}/{class}.md`
- [ ] 元信息完整：`命名空间`、`类型`、`描述`
- [ ] 类总览页的公共方法表格中，每个方法都有对应的详情页
- [ ] 代码块使用 ``` 包裹，语言标识正确（`cpp`）

### 2. 引用校验

- [ ] 所有 `./{method}.md` 链接指向的文件存在
- [ ] 引用路径使用相对路径
- [ ] 不存在循环引用

### 3. 内容校验

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

---

## 生成流程

1. **扫描源码**：分析指定目录下的头文件
2. **识别 API**：查找 `class`、`struct`、`enum`、`namespace`
3. **提取信息**：从源码中提取方法签名、成员变量、枚举值、文档注释
4. **创建结构**：为每个类创建文件夹，生成类总览页和方法详情页
5. **生成文档**：按照上述模板生成 Markdown 文件
6. **校验输出**：运行校验规则，检查格式和引用
7. **输出报告**：列出生成的文档和发现的问题

---

## 使用示例

用户输入：

完善 docs/api 文档，检查并修复错误

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