refactor api documentation structure
This commit is contained in:
@@ -1,450 +1,277 @@
|
||||
# XCEngine API 文档编写与校验 Skill
|
||||
# XCEngine API Documentation Skill
|
||||
|
||||
## 用途
|
||||
## 目标
|
||||
|
||||
根据 XCEngine C++ 引擎源码生成符合规范的 API 文档，并进行格式校验和查漏补缺。
|
||||
本规范用于为 `XCEngine` 生成和维护一套唯一的 canonical API 文档。
|
||||
|
||||
在开始编写任何文档之前，必须先完整阅读并深刻理解对应的源码上下文——包括设计目的、
|
||||
实现细节、边界条件、线程安全约定、与其他模块的依赖关系等。切忌在未读懂源码的情况下
|
||||
仅凭方法签名或猜测来编写文档。
|
||||
硬性要求：
|
||||
|
||||
---
|
||||
1. `docs/api/XCEngine/**` 必须与 `engine/include/XCEngine/**` 严格平行。
|
||||
2. 模块、子模块、类型、方法的命名必须稳定并贴近源码符号名。
|
||||
3. 不保留第二套正式文档树。历史文档只允许作为迁移过程中的临时材料，迁移完成后必须删除。
|
||||
|
||||
## 文档目录结构
|
||||
在编写任何 API 文档之前，必须先阅读对应头文件与相关实现，理解职责、边界、生命周期、线程语义、错误条件和依赖关系。禁止只根据函数名猜测含义。
|
||||
|
||||
```
|
||||
## Canonical 目录结构
|
||||
|
||||
```text
|
||||
docs/api/
|
||||
├── main.md # 总索引
|
||||
├── {module}/
|
||||
│ ├── {module}.md # 模块总览页
|
||||
│ ├── {class}/
|
||||
│ │ ├── {class}.md # 类/结构体/枚举总览页
|
||||
│ │ ├── {method}.md # 方法详情页
|
||||
│ │ └── ...
|
||||
├── main.md
|
||||
├── XCEngine/
|
||||
│ ├── XCEngine.md
|
||||
│ ├── Debug/
|
||||
│ │ ├── Debug.md
|
||||
│ │ ├── Logger/
|
||||
│ │ │ ├── Logger.md
|
||||
│ │ │ ├── Log.md
|
||||
│ │ │ ├── SetLevel.md
|
||||
│ │ │ ├── Constructor.md
|
||||
│ │ │ └── Destructor.md
|
||||
│ │ └── RenderDocCapture/
|
||||
│ │ ├── RenderDocCapture.md
|
||||
│ │ └── TriggerCapture.md
|
||||
│ ├── Core/
|
||||
│ │ ├── Core.md
|
||||
│ │ ├── Asset/
|
||||
│ │ │ ├── Asset.md
|
||||
│ │ │ └── ResourceManager/
|
||||
│ │ │ ├── ResourceManager.md
|
||||
│ │ │ └── Load.md
|
||||
│ │ └── Math/
|
||||
│ │ └── Math.md
|
||||
│ └── ...
|
||||
└── ...
|
||||
├── _meta/
|
||||
└── _tools/
|
||||
```
|
||||
|
||||
**命名规则：**
|
||||
## 强制命名规则
|
||||
|
||||
- 模块总览：`{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. 目录总览页
|
||||
|
||||
---
|
||||
- 根目录总览页必须是 `docs/api/XCEngine/XCEngine.md`
|
||||
- 模块总览页必须使用 `{ModuleName}.md`
|
||||
- 子模块总览页必须使用 `{SubmoduleName}.md`
|
||||
- canonical 目录下禁止使用 `README.md` 作为模块或子模块总览页
|
||||
|
||||
## 页面类型与模板
|
||||
示例：
|
||||
|
||||
### 1. 模块总览页
|
||||
- `docs/api/XCEngine/Debug/Debug.md`
|
||||
- `docs/api/XCEngine/Core/Core.md`
|
||||
- `docs/api/XCEngine/Core/Asset/Asset.md`
|
||||
- `docs/api/XCEngine/RHI/D3D12/D3D12.md`
|
||||
|
||||
### 2. 类型目录
|
||||
|
||||
- 每个 public 类型或以 header 为单位的主声明，都必须是一个独立文件夹
|
||||
- 文件夹名必须与源码中的类型名或 header stem 保持一致
|
||||
- 保留原始大小写
|
||||
|
||||
示例：
|
||||
|
||||
- `docs/api/XCEngine/Debug/Logger/`
|
||||
- `docs/api/XCEngine/Core/Asset/ResourceManager/`
|
||||
- `docs/api/XCEngine/RHI/D3D12/D3D12Device/`
|
||||
|
||||
### 3. 类型总览页
|
||||
|
||||
- 类型总览页固定为 `{TypeName}/{TypeName}.md`
|
||||
- 不允许把类型总览页直接平铺在模块目录下
|
||||
|
||||
### 4. 方法详情页
|
||||
|
||||
- 方法详情页必须放在所属类型文件夹内
|
||||
- 方法页文件名优先使用原函数名
|
||||
- 保留 PascalCase / camelCase / 全大写缩写
|
||||
- 禁止改成 lowercase kebab-case
|
||||
- 同名重载共用一个方法页
|
||||
|
||||
示例：
|
||||
|
||||
- `Get.md`
|
||||
- `CreateBuffer.md`
|
||||
- `SetRenderTarget.md`
|
||||
- `LoadSceneAsync.md`
|
||||
- `GetCPUHandle.md`
|
||||
|
||||
### 5. 特殊方法命名
|
||||
|
||||
- 构造函数使用 `Constructor.md`
|
||||
- 析构函数使用 `Destructor.md`
|
||||
- 运算符重载使用可读的 PascalCase 名称
|
||||
|
||||
推荐映射：
|
||||
|
||||
- `operator=` -> `OperatorAssign.md`
|
||||
- `operator+=` -> `OperatorPlusAssign.md`
|
||||
- `operator[]` -> `OperatorSubscript.md`
|
||||
- `operator()` -> `OperatorCall.md`
|
||||
- `operator bool` -> `OperatorBool.md`
|
||||
|
||||
## 页面职责
|
||||
|
||||
### 1. 目录总览页
|
||||
|
||||
负责：
|
||||
|
||||
- 说明模块或子模块的职责边界
|
||||
- 列出直接子目录
|
||||
- 列出当前目录下的 public headers 对应类型入口
|
||||
- 提供父级目录和 `docs/api/main.md` 的导航
|
||||
|
||||
不负责：
|
||||
|
||||
- 展开详细方法级说明
|
||||
- 复制头文件全部声明
|
||||
- 保留迁移说明、旧入口跳转或双轨文档提示
|
||||
|
||||
### 2. 类型总览页
|
||||
|
||||
负责：
|
||||
|
||||
- 标识命名空间、类型、头文件、职责
|
||||
- 给出声明概览
|
||||
- 列出公开字段、枚举值或公开方法
|
||||
- 作为该类型所有方法详情页的稳定入口
|
||||
|
||||
### 3. 方法详情页
|
||||
|
||||
负责：
|
||||
|
||||
- 给出准确签名
|
||||
- 按重载分节
|
||||
- 说明参数、返回值、生命周期、线程语义和关键约束
|
||||
- 给出最小但可信的示例
|
||||
|
||||
## 推荐页面模板
|
||||
|
||||
### 1. 目录总览页模板
|
||||
|
||||
```markdown
|
||||
# {ModuleName} 模块概览
|
||||
# {DirName}
|
||||
|
||||
**命名空间**: `{namespace}`
|
||||
**命名空间**: `{Namespace}`
|
||||
|
||||
**类型**: `module`
|
||||
**类型**: `module` / `submodule` / `module-root`
|
||||
|
||||
**描述**: {模块一句话描述}
|
||||
**描述**: {一句话说明当前目录职责}
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
{模块功能详细介绍}
|
||||
{说明该目录在整个引擎中的职责边界、使用场景和与相邻模块的关系}
|
||||
|
||||
## 模块内容
|
||||
## 子目录
|
||||
|
||||
### {子分类名}
|
||||
- [ChildA](ChildA/ChildA.md)
|
||||
- [ChildB](ChildB/ChildB.md)
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [{ComponentName}](component/component.md) | `{Header.h}` | {描述} |
|
||||
...
|
||||
## 头文件
|
||||
|
||||
## {可选：对标/对比表格}
|
||||
|
||||
| 选项 | 适用场景 | 特点 |
|
||||
|------|----------|------|
|
||||
| `Foo` | 场景A | 特点X |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
```
|
||||
- [TypeA](TypeA/TypeA.md) - `TypeA.h`
|
||||
- [TypeB](TypeB/TypeB.md) - `TypeB.h`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [{DocName}](../{module}/{doc}.md) - {描述}
|
||||
- [上级目录](../{ParentDir}.md)
|
||||
- [API 总索引](../../main.md)
|
||||
```
|
||||
|
||||
### 2. 类总览页
|
||||
### 2. 类型总览页模板
|
||||
|
||||
```markdown
|
||||
# {ClassName}
|
||||
# {TypeName}
|
||||
|
||||
**命名空间**: `{namespace}`
|
||||
**命名空间**: `{Namespace}`
|
||||
|
||||
**类型**: `class` / `class (abstract)` / `class (singleton)`
|
||||
**类型**: `class` / `class (abstract)` / `class (singleton)` / `struct` / `enum class`
|
||||
|
||||
**头文件**: `XCEngine/Path/Header.h`
|
||||
**头文件**: `XCEngine/.../{Header}.h`
|
||||
|
||||
**描述**: {一句话功能描述}
|
||||
**描述**: {一句话说明}
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
{类的详细介绍}
|
||||
{描述该类型的职责、拥有关系、状态约束、典型使用方式}
|
||||
|
||||
## {可选章节}
|
||||
## 声明概览
|
||||
|
||||
### 类型别名
|
||||
|
||||
| 别名 | 类型 | 描述 |
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `SizeType` | `size_t` | 大小类型 |
|
||||
|
||||
### 常量
|
||||
|
||||
| 常量 | 值 | 描述 |
|
||||
|------|-----|------|
|
||||
| `static constexpr SizeType npos` | `-1` | 无效位置标识 |
|
||||
| `{TypeName}` | `class` | {说明} |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [{MethodName}](method-name.md) | {描述} |
|
||||
| `virtual ~ClassName()` | 虚析构函数 |
|
||||
|
||||
## 受保护方法（如有）
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ClassName()` | 默认构造函数 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
```
|
||||
| [Initialize](Initialize.md) | {描述} |
|
||||
| [Shutdown](Shutdown.md) | {描述} |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [{RelatedClass}](../module/class.md) - {描述}
|
||||
- [当前目录](../{DirName}.md)
|
||||
```
|
||||
|
||||
### 3. Struct 总览页
|
||||
### 3. 方法详情页模板
|
||||
|
||||
```markdown
|
||||
# {StructName}
|
||||
# {TypeName}::{MethodName}
|
||||
|
||||
**命名空间**: `{namespace}`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Path/Header.h`
|
||||
|
||||
**描述**: {一句话功能描述}
|
||||
|
||||
## 结构体成员
|
||||
|
||||
| 成员 | 类型 | 描述 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| [{memberName}](membername.md) | `type` | {描述} | {默认值} |
|
||||
|
||||
## 使用示例
|
||||
{一句话说明方法职责}
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
{完整签名}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
{方法行为说明，包括前置条件、后置条件、副作用和失败语义}
|
||||
|
||||
- [{RelatedDoc}](../module/doc.md) - {描述}
|
||||
```
|
||||
|
||||
### 4. Enum 总览页
|
||||
|
||||
```markdown
|
||||
# {EnumName}
|
||||
|
||||
**命名空间**: `{namespace}`
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**头文件**: `XCEngine/Path/Header.h`
|
||||
|
||||
## 概述
|
||||
|
||||
{枚举用途描述}
|
||||
|
||||
## 枚举值
|
||||
|
||||
| 枚举值 | 数值 | 描述 |
|
||||
|--------|------|------|
|
||||
| `ValueName` | {N} | {描述} |
|
||||
...
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [{RelatedDoc}](../module/doc.md) - {描述}
|
||||
```
|
||||
|
||||
### 5. 方法详情页（单重载）
|
||||
|
||||
```markdown
|
||||
# {ClassName}::{MethodName}
|
||||
|
||||
{一句话描述方法功能}
|
||||
|
||||
```cpp
|
||||
{完整方法签名}
|
||||
```
|
||||
|
||||
{详细描述，包括设计目的和使用场景}
|
||||
|
||||
**参数：**
|
||||
- `paramName` - {参数描述}
|
||||
|
||||
**返回：** {返回值类型} - {返回值含义}
|
||||
|
||||
**线程安全：** ✅ / ❌ {可选说明}
|
||||
|
||||
**复杂度：** O(n) {可选}
|
||||
|
||||
**注意：** {可选，重要警告或注意事项}
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [{ClassName} 总览](class-name.md)
|
||||
- [{RelatedMethod}](related-method.md)
|
||||
```
|
||||
|
||||
### 6. 方法详情页（多重载）
|
||||
|
||||
当方法有多个重载时，使用 `## 重载 N:` 分节：
|
||||
|
||||
```markdown
|
||||
# {ClassName}::{MethodName}
|
||||
|
||||
{一句话描述方法功能}
|
||||
|
||||
## 重载 1: {简短描述}
|
||||
|
||||
```cpp
|
||||
{签名1}
|
||||
```
|
||||
|
||||
{描述}
|
||||
|
||||
**参数：**
|
||||
**参数**
|
||||
- `param` - {描述}
|
||||
|
||||
**返回：** {类型} - {含义}
|
||||
**返回**
|
||||
- `{Type}` - {描述}
|
||||
|
||||
**复杂度：** O(n)
|
||||
**线程语义**
|
||||
- {线程安全 / 只能主线程 / 调用方同步等}
|
||||
|
||||
## 重载 2: {简短描述}
|
||||
**示例**
|
||||
|
||||
```cpp
|
||||
{签名2}
|
||||
```
|
||||
|
||||
...
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
{完整可运行代码}
|
||||
{最小可信示例}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [{ClassName} 总览](class-name.md)
|
||||
- [返回类型总览]({TypeName}.md)
|
||||
- [返回模块目录](../{DirName}.md)
|
||||
```
|
||||
|
||||
---
|
||||
## 文风与质量要求
|
||||
|
||||
## 元信息字段规范
|
||||
- 使用工程化、可审阅、可维护的描述，不写空话
|
||||
- 描述职责边界，而不是复述函数名
|
||||
- 线程、生命周期、资源所有权、错误条件必须明确
|
||||
- 示例必须与当前 public API 一致，不允许伪代码式胡写
|
||||
- 信息应放在正确层级，避免模块页和类型页职责混淆
|
||||
- 禁止生成双轨入口或保留旧目录跳转
|
||||
|
||||
| 字段 | 必需 | 适用页面 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| `**命名空间**` | 是 | 所有 | C++ 命名空间 |
|
||||
| `**类型**` | 是 | 所有 | `class`、`struct`、`enum class`、`module` 等；class 可加修饰如 `(abstract)`、`(singleton)` |
|
||||
| `**描述**` | 是 | 所有 | 一句话功能描述 |
|
||||
| `**头文件**` | 是 | 类/struct/enum | 相对路径形式，如 `XCEngine/Threading/Task.h` |
|
||||
## 重构与生成流程
|
||||
|
||||
---
|
||||
1. 扫描 `engine/include/XCEngine/**`
|
||||
2. 建立与源码平行的 `docs/api/XCEngine/**` 目录树
|
||||
3. 为每个源码目录生成 `{DirName}.md` 目录总览页
|
||||
4. 为每个 public header 生成 `{TypeName}/{TypeName}.md`
|
||||
5. 为每个公开方法生成 `{TypeName}/{MethodName}.md`
|
||||
6. 清理旧的 lowercase kebab-case 方法页和旧的 flat header 页面
|
||||
7. 删除迁移完成后的历史文档
|
||||
8. 审计链接、头文件引用覆盖率和目录索引完整性
|
||||
|
||||
## 必需章节规范
|
||||
## 验收清单
|
||||
|
||||
### 模块总览页
|
||||
|
||||
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 的类，在方法列表后加：
|
||||
|
||||
```markdown
|
||||
## 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. 输出生成报告和问题列表
|
||||
- `docs/api/XCEngine/**` 与 `engine/include/XCEngine/**` 目录结构平行
|
||||
- canonical 目录下没有模块级 `README.md`
|
||||
- 每个类型都是一个独立文件夹
|
||||
- 每个类型总览页都是 `{TypeName}/{TypeName}.md`
|
||||
- 方法页文件名使用原函数名或规范化运算符名
|
||||
- `docs/api/main.md` 指向 `docs/api/XCEngine/XCEngine.md`
|
||||
- 所有 canonical `.md` 链接可解析
|
||||
- 所有 public headers 都有对应 canonical 文档入口
|
||||
- 仓库中不存在第二套正式 API 文档树
|
||||
|
||||
Reference in New Issue
Block a user