342 lines
7.7 KiB
Markdown
342 lines
7.7 KiB
Markdown
# 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. 输出生成报告和问题列表
|