ssdfasd
dc850d7739
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
185 lines
4.5 KiB
Markdown
185 lines
4.5 KiB
Markdown
# 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`）
|
||
|
||
### 类总览页模板
|
||
|
||
```markdown
|
||
# {类名称}
|
||
|
||
**命名空间**: `{namespace}`
|
||
|
||
**类型**: `{type}`
|
||
|
||
**描述**: {一句话功能描述}
|
||
|
||
## 概述
|
||
|
||
{模块功能详细介绍，包括设计目的和使用场景}
|
||
|
||
## 公共方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [`Emplace`](./emplace.md) | 原地构造元素 |
|
||
| [`Push`](./push.md) | 末尾添加元素 |
|
||
|
||
## 使用示例
|
||
|
||
```cpp
|
||
{代码示例}
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [{文档名}](./{filename}.md) - {简短描述}
|
||
```
|
||
|
||
### 方法详情页模板
|
||
|
||
```markdown
|
||
# {类名称}::{方法名}
|
||
|
||
```cpp
|
||
{完整方法签名}
|
||
```
|
||
|
||
{方法详细描述，包括设计目的、使用场景、注意事项}
|
||
|
||
**参数：**
|
||
- `{param}` - {参数描述}
|
||
|
||
**返回：** {返回值描述}
|
||
|
||
**异常：** （如有）
|
||
|
||
**线程安全：** ✅ / ❌
|
||
|
||
**复杂度：** O(n)
|
||
|
||
**示例：**
|
||
|
||
```cpp
|
||
{可运行的完整示例代码}
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [{类总览}](./{class}.md) - 返回类总览
|
||
```
|
||
|
||
---
|
||
|
||
## 必需字段规范
|
||
|
||
### 元信息（必须）
|
||
|
||
- `**命名空间**`: 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. 输出生成报告和问题列表
|