XCEngine/docs/api-skill.md

XCEngine API 文档编写与校验 Skill

用途

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

在开始编写任何文档之前，必须先完整阅读并深刻理解对应的源码上下文——包括设计目的、 实现细节、边界条件、线程安全约定、与其他模块的依赖关系等。切忌在未读懂源码的情况下 仅凭方法签名或猜测来编写文档。

---

文档目录结构

docs/api/
├── main.md                     # 总索引
├── {module}/
│   ├── {module}.md            # 模块总览页
│   ├── {class}/
│   │   ├── {class}.md         # 类/结构体/枚举总览页
│   │   ├── {method}.md        # 方法详情页
│   │   └── ...
│   └── ...
└── ...

命名规则：

• 模块总览：{module}/{module}.md（如 threading/threading.md）
• 类/结构体文件夹：{class-name}/（小写，如 task-group/）
• 类总览页：{class-name}/{class-name}.md
• 方法详情页：{class-name}/{method-name}.md
• 构造函数/析构函数：constructor.md、destructor.md、~typename.md
• 运算符重载：operator-assign.md、operator-plus.md、operator-subscript.md
• 枚举详情页（单独文件夹时）：{enum-name}/{enum-name}.md

---

页面类型与模板

1. 模块总览页

# {ModuleName} 模块概览

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

**类型**: `module`

**描述**: {模块一句话描述}

## 概述

{模块功能详细介绍}

## 模块内容

### {子分类名}

| 组件 | 文件 | 描述 |
|------|------|------|
| [{ComponentName}](component/component.md) | `{Header.h}` | {描述} |
...

## {可选：对标/对比表格}

| 选项 | 适用场景 | 特点 |
|------|----------|------|
| `Foo` | 场景A | 特点X |

## 使用示例

```cpp
{完整可运行代码}

相关文档

• {DocName} - {描述}

### 2. 类总览页

```markdown
# {ClassName}

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

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

**头文件**: `XCEngine/Path/Header.h`

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

## 概述

{类的详细介绍}

## {可选章节}

### 类型别名

| 别名 | 类型 | 描述 |
|------|------|------|
| `SizeType` | `size_t` | 大小类型 |

### 常量

| 常量 | 值 | 描述 |
|------|-----|------|
| `static constexpr SizeType npos` | `-1` | 无效位置标识 |

## 公共方法

| 方法 | 描述 |
|------|------|
| [{MethodName}](method-name.md) | {描述} |
| `virtual ~ClassName()` | 虚析构函数 |

## 受保护方法（如有）

| 方法 | 描述 |
|------|------|
| `ClassName()` | 默认构造函数 |

## 使用示例

```cpp
{完整可运行代码}

相关文档

• {RelatedClass} - {描述}

### 3. Struct 总览页

```markdown
# {StructName}

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

**类型**: `struct`

**头文件**: `XCEngine/Path/Header.h`

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

## 结构体成员

| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| [{memberName}](membername.md) | `type` | {描述} | {默认值} |

## 使用示例

```cpp
{完整可运行代码}

相关文档

• {RelatedDoc} - {描述}

### 4. Enum 总览页

```markdown
# {EnumName}

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

**类型**: `enum class`

**头文件**: `XCEngine/Path/Header.h`

## 概述

{枚举用途描述}

## 枚举值

| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `ValueName` | {N} | {描述} |
...

## 使用示例

```cpp
{完整可运行代码}

相关文档

• {RelatedDoc} - {描述}

### 5. 方法详情页（单重载）

```markdown
# {ClassName}::{MethodName}

{一句话描述方法功能}

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

{详细描述，包括设计目的和使用场景}

参数：

• paramName - {参数描述}

返回： {返回值类型} - {返回值含义}

线程安全： ✅ / ❌ {可选说明}

复杂度： O(n) {可选}

注意： {可选，重要警告或注意事项}

示例：

{完整可运行代码}

相关文档

• {ClassName} 总览
• {RelatedMethod}

### 6. 方法详情页（多重载）

当方法有多个重载时，使用 `## 重载 N:` 分节：

```markdown
# {ClassName}::{MethodName}

{一句话描述方法功能}

## 重载 1: {简短描述}

```cpp
{签名1}

{描述}

参数：

• param - {描述}

返回： {类型} - {含义}

复杂度： O(n)

重载 2: {简短描述}

{签名2}

...

线程安全： ✅

示例：

{完整可运行代码}

相关文档

• {ClassName} 总览

---

## 元信息字段规范

| 字段 | 必需 | 适用页面 | 说明 |
|------|------|----------|------|
| `**命名空间**` | 是 | 所有 | C++ 命名空间 |
| `**类型**` | 是 | 所有 | `class`、`struct`、`enum class`、`module` 等；class 可加修饰如 `(abstract)`、`(singleton)` |
| `**描述**` | 是 | 所有 | 一句话功能描述 |
| `**头文件**` | 是 | 类/struct/enum | 相对路径形式，如 `XCEngine/Threading/Task.h` |

---

## 必需章节规范

### 模块总览页

1. `## 概述` — 模块功能介绍
2. `## 模块内容` — 分类表格（含组件名、文件、描述三列）
3. `## 使用示例` — 完整代码
4. `## 相关文档` — 交叉引用

### 类总览页

1. `## 概述` — 类功能介绍
2. `## 公共方法` — 方法列表（纯虚方法加标注 `(pure virtual)`）
3. `## 受保护方法` — 如有
4. `## 使用示例` — 完整代码
5. `## 相关文档` — 交叉引用

### Struct 总览页

1. `## 结构体成员` — 成员表格（含类型、描述、默认值三列）
2. `## 使用示例` — 完整代码
3. `## 相关文档` — 交叉引用

### Enum 总览页

1. `## 枚举值` — 枚举值表格（含枚举值、数值、描述三列）
2. `## 使用示例` — 完整代码
3. `## 相关文档` — 交叉引用

### 方法详情页

1. **方法签名** — 完整 `cpp` 代码块
2. **详细描述** — 语义和使用场景
3. **参数列表** — 每个参数的含义
4. **返回值** — 类型和含义
5. **示例代码** — 完整可运行代码
6. **相关文档** — 返回类总览的链接

---

## 链接规范

- 同一类文件夹内跳转：`[MethodName](method-name.md)`
- 指向类总览：`[ClassName 总览](class-name.md)`
- 指向模块总览：`[../module.md](../module.md)` 或 `[模块名](../module.md)`
- 跨模块跳转：`[{DocName}](../module/class.md)`
- 链接文本使用中文（如"返回类总览"）而非英文

---

## 特殊章节

### Singleton 类

Singleton 类在 `## 公共方法` 后可加 `## 单例访问` 章节：

```markdown
## 单例访问

| 方法 | 描述 |
|------|------|
| `static ClassName& Get()` | 获取单例实例 |

std::hash 特化

String 等需要 hash 的类，在方法列表后加：

## std::hash 特化

```cpp
namespace std {
    template<>
    struct hash<XCEngine::Containers::String> {
        size_t operator()(const XCEngine::Containers::String& str) const noexcept;
    };
}

{描述 hash 算法细节}

### 构造函数详细表

某些类（如 ConsoleLogSink）在类总览页末尾用表格记录构造函数参数默认值：

```markdown
## 构造函数详细

| 属性 | 值 |
|------|-----|
| 默认 `m_colorOutput` | `true` |

---

代码示例规范

• 语言标签：cpp
• 包含必要的 #include
• 示例完整可运行（不是代码片段）
• 代码注释使用中文

---

线程安全标注

• ✅ — 线程安全
• ❌ — 非线程安全
• 可附加括号说明：✅ (内部使用 mutex 保护)

---

文档一致性检查

生成或修改文档时，需检查：

1. 元信息完整性 — 每页都有命名空间、类型、描述、头文件（类/struct/enum）
2. 链接有效性 — 所有相对链接指向的文件确实存在
3. 内容无重复 — 同一页面中不要出现重复的描述、参数、示例等
4. 类型匹配 — **类型** 字段与实际 C++ 类型一致
5. 枚举数值 — enum 页面包含数值列
6. 默认值 — struct 页面成员表格包含默认值列
7. 命名一致 — 页面文件名与 H1 标题一致

---

生成流程

核心原则：在动手写文档之前，必须先完整阅读并深刻理解源码上下文。

1. 阅读源码：完整阅读目标类的头文件（.h）和实现文件（.cpp），理解设计意图、数据成员、 工作流程、边界条件、线程安全约定、与其他模块的依赖关系。不要只看签名就写文档。
2. 扫描提取：在充分理解的基础上，系统性提取方法签名、成员变量、枚举值、文档注释等信息。
3. 创建结构：为每个类创建文件夹，生成类总览页和方法详情页。
4. 检查一致性：运行链接检查、字段完整性检查。
5. 补充缺失：对照源码，检查现有文档是否完整，如有缺失的 .md 文件（类总览页、方法详情页等） 必须自行创建；如现有文档中缺少示例、枚举值说明、参数描述等内容，也要自行补充完整，不要留空。
6. 输出报告：列出生成文件列表、缺失内容、发现的问题。

---

使用示例

用户输入：

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

AI 执行：

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