API_Template

API 文档模板规范

本文档定义了 utilsCore API 文档的标准模板和编写规范。所有 API 文档应遵循此模板以确保一致性和可读性。

---

文档结构

1. 标题

# [类/模块名] API 文档

2. 概述

## 概述

[类/模块名] 是 utilsCore [模块名] 的核心类，提供[功能描述]。

### 职责

- [职责1]
- [职责2]
- [职责3]

### 适用场景

- [场景1]
- [场景2]
- [场景3]

### 依赖关系

- 依赖: [依赖模块]
- 被依赖: [被依赖模块]

3. 类/结构体分析

## 类/结构体分析

### [类名] 类

#### 职责与用途

[类的职责和用途描述]

#### 设计模式

- **[模式名]**: [模式说明]
- **[模式名]**: [模式说明]

4. 结构体定义

### [结构体名] 结构体

#### 职责与用途

[结构体的职责和用途描述]

#### 结构体定义

```cpp
struct [结构体名] {
    [类型] [字段名];  // [说明]
    [类型] [字段名];  // [说明]
};

字段说明

字段	类型	说明
[字段名]	[类型]	[说明]

### 5. API 方法文档

```markdown
## 公共 API 方法

### [方法名]() - [方法描述]

```cpp
[返回类型] [方法名]([参数列表]);

参数说明:

• [参数名] (输入/输出): [参数说明]

返回值:

• [返回值说明]

所有权归属:

• [所有权规则]

注意事项:

1. [注意事项1]
2. [注意事项2]

使用例程:

// [使用例程]

### 6. 枚举定义

```markdown
## 枚举定义

### [枚举名] 枚举

#### 枚举值

| 值 | 说明 |
|----|------|
| `[枚举值]` | `[说明]` |
| `[枚举值]` | `[说明]` |

7. 线程安全说明

## 线程安全说明

### 同步机制

- **[同步机制1]**: [说明]
- **[同步机制2]**: [说明]

### 线程安全建议

- [建议1]
- [建议2]

8. 典型使用场景

## 典型使用场景

### 场景 1: [场景标题]

```cpp
// [代码示例]

场景 2: [场景标题]

// [代码示例]

**要求**: 至少提供 5 个典型使用场景

### 9. 注意事项

```markdown
## 注意事项

1. **[要点1]**: [详细说明]
2. **[要点2]**: [详细说明]
3. **[要点3]**: [详细说明]

要求: 至少提供 8 个注意事项

10. 相关文档

## 相关文档

- [相关文档1](./路径) - [说明]
- [相关文档2](./路径) - [说明]

11. 参考资料

## 参考资料

- [参考资料1](URL)
- [参考资料2](URL)

12. 版本历史

## 版本历史

- v1.0 - 初始版本，支持基本功能

---

编写规范

标题规范

1. 使用 # 表示一级标题（文档标题）
2. 使用 ## 表示二级标题（章节）
3. 使用 ### 表示三级标题（子章节）

代码块规范

1. 使用 ```cpp 标记 C++ 代码
2. 使用 ```markdown 标记 Markdown 代码
3. 代码缩进使用 4 个空格
4. 注释使用 // 格式

表格规范

1. 表头使用 | 分隔
2. 表格内容左对齐
3. 必要时添加表格说明

链接规范

1. 使用相对路径引用文档：./模块/文档名.md
2. 使用绝对路径引用外部资源：https://example.com
3. 链接文本简明扼要

格式规范

1. 参数说明使用 (输入) / (输出) 标注方向
2. 返回值使用 - 列表说明
3. 所有权归属必须明确说明
4. 注意事项使用编号列表

---

内容要求

概述部分

• 必须说明类的职责
• 必须说明适用场景
• 必须说明依赖关系

API 方法部分

• 必须提供完整的函数签名
• 必须说明所有参数
• 必须说明返回值
• 必须说明所有权归属
• 必须提供使用例程

使用场景部分

• 至少提供 5 个典型场景
• 场景必须具有代表性
• 代码必须可运行

注意事项部分

• 至少提供 8 个注意事项
• 注意事项必须具有实际意义
• 必须覆盖常见陷阱

---

质量检查清单

• 文档标题正确
• 概述完整（职责、场景、依赖）
• 类/结构体分析完整
• 所有 API 方法都有文档
• 参数说明完整
• 返回值说明完整
• 所有权归属明确
• 使用例程正确
• 至少 5 个使用场景
• 至少 8 个注意事项
• 线程安全说明完整
• 相关文档链接正确
• 参考资料链接有效
• 版本历史完整

---

示例文档

参考以下文档作为示例：

• DmaBuffer - 完整的类文档示例
• DeviceController - 复杂类文档示例
• Base - 工具类文档示例
• Logger - 单例模式示例

---

常见问题

Q: 如何命名文档？

A: 文档命名格式为 [类名]_wiki.md，使用小写字母和下划线。

Q: 如何组织代码示例？

A: 代码示例应包含完整的上下文，能够独立编译和运行。

Q: 如何描述所有权归属？

A: 明确说明参数和返回值的所有权，使用以下格式：

• "返回值由调用者持有"
• "参数所有权由调用者管理"
• "无所有权转移"

Q: 如何处理线程安全？

A: 必须提供线程安全说明，包括同步机制和使用建议。

---

维护指南

更新文档

当 API 发生变化时，必须同步更新文档：

1. 更新函数签名
2. 更新参数说明
3. 更新使用例程
4. 更新版本历史

审查文档

定期审查文档以确保准确性：

1. 检查代码示例是否可运行
2. 检查链接是否有效
3. 检查描述是否准确

版本管理

使用版本历史记录文档变更：

• v1.0 - 初始版本
• v1.1 - [变更说明]
• v2.0 - [重大变更说明]

---

联系方式

如有问题或建议，请联系：

• 项目仓库: https://github.com/SweerItTer/EdgeVision-app
• 文档维护: [维护者信息]