# ARCS 平台驱动设备文档编写规范

本规范基于 lisa_adc、lisa_gpio、lisa_uart 三个驱动文档的分析总结而成，旨在为 ARCS 平台的驱动开发提供统一的文档编写标准。

## 一、文档结构规范

### 1.1 标题与简介（必需）

**格式**:
```markdown
# <驱动名称> 驱动

基于 lisa_device 框架的 <设备类型> 设备驱动，为 ARCS 平台提供统一的<功能描述>接口。
```

**要求**:
- 标题使用一级标题，格式为 "<驱动名称> 驱动"
- 简介一句话说明驱动的定位和用途
- 必须提及基于 lisa_device 框架
- 必须说明为 ARCS 平台提供的核心功能

**示例**:
```markdown
# ADC 驱动

基于 lisa_device 框架的 ADC 设备驱动，为 ARCS 平台提供统一的模拟信号采样接口。
```

### 1.2 功能特性（必需）

**格式**:
```markdown
## 功能特性

- **特性名称**: 特性说明
- **特性名称**: 特性说明
...
```

**要求**:
- 使用二级标题 "功能特性"
- 使用无序列表，每项使用 `**粗体**` 突出特性名称
- 按重要性排序：设备支持 → 核心功能 → 高级功能
- 5-8 个要点，简洁明了
- 必须包含的特性：设备支持、核心功能、线程安全（如果支持）

**示例**:
```markdown
## 功能特性

- **设备支持**: UART0、UART1、UART2 三个串口设备
- **传输模式**: 支持中断模式和 DMA 模式
- **通信配置**: 灵活配置波特率、数据位、停止位、校验位、流控
- **数据传输**: 同步/异步读写、轮询收发
- **线程安全**: 支持全双工通信，可在多线程环境中使用
```

### 1.3 配置选项（必需）

**格式**:
```markdown
## 配置选项

在 `prj.conf` 中启用驱动：

​```kconfig
CONFIG_LISA_<驱动名称>=y
CONFIG_LISA_<设备1>=y        # 启用说明（可选）
CONFIG_LISA_<设备2>=y        # 启用说明（可选）
​```

根据需要选择启用的设备或功能。
```

**要求**:
- 使用二级标题 "配置选项"
- 明确说明配置文件位置（prj.conf 或 Kconfig）
- 使用 kconfig 代码块
- 提供必需和可选配置项
- 对每个配置项添加注释说明（如果有多个选项）

### 1.4 API 接口（必需）

**格式**:
```markdown
## API 接口

### <功能分类1>

​```c
函数原型1;
函数原型2;
​```

功能说明（可选）。

### <功能分类2>

​```c
函数原型1;
函数原型2;
​```

功能说明（可选）。
```

**要求**:
- 使用二级标题 "API 接口"
- 按功能分类组织，使用三级标题
- 常见分类：配置接口、数据传输接口、控制接口、中断管理等
- 仅提供函数原型，详细说明放在后续章节
- 如有重要提示，使用 **粗体** 或 `代码` 强调

**示例**:
```markdown
## API 接口

### 配置接口

​```c
int lisa_uart_configure(lisa_device_t *dev, const lisa_uart_config_t *config);
int lisa_uart_get_config(lisa_device_t *dev, lisa_uart_config_t *config);
​```

**重要**: 必须先调用 `lisa_uart_configure()` 配置设备后，才能使用下面的功能 API。

### 数据传输接口

​```c
int lisa_uart_write_sync(lisa_device_t *dev, const uint8_t *buf, uint32_t len, uint32_t timeout_ms);
int lisa_uart_read_sync(lisa_device_t *dev, uint8_t *buf, uint32_t len);
​```
```

### 1.5 使用示例/使用方法（必需）

**格式**:

**方式一：基本步骤 + 示例**（适用于步骤明确的驱动，如 ADC）
```markdown
## 使用方法

### 基本步骤

1. **步骤名称**: 步骤说明
2. **步骤名称**: 步骤说明
3. **步骤名称**: 步骤说明

### 基础使用示例

​```c
// 完整代码示例
​```

### 进阶示例1

​```c
// 完整代码示例
​```
```

**方式二：直接示例**（适用于使用模式多样的驱动，如 GPIO、UART）
```markdown
## 使用示例

### 场景1名称

​```c
// 完整代码示例
​```

### 场景2名称

​```c
// 完整代码示例
​```
```

**要求**:
- 使用二级标题 "使用示例" 或 "使用方法"
- 每个示例使用三级标题，标题应清晰描述使用场景
- 代码必须完整可运行，包含必要的头文件、错误处理
- 代码注释清晰，使用 `//` 单行注释说明步骤
- 从简单到复杂排序
- 至少提供 2-3 个典型使用场景
- 示例应覆盖主要 API 的使用

**代码风格**:
- 使用行内注释 `// 说明` 而非块注释
- 注释使用中文
- 关键步骤前添加序号注释：`// 1. 获取设备`
- 错误处理要简洁但完整

### 1.6 硬件配置（必需）

**格式**:
```markdown
## 硬件配置

### 引脚复用配置

<驱动名称> 驱动在初始化时会自动调用板型目录中定义的 `lisa_<驱动>_pinmux()` 函数，用于配置引脚复用。

**配置位置**:
- **定义**: `boards/<板型名>/pinmux.c` 中实现函数
- **声明**: `boards/<板型名>/pinmux.h` 中声明函数
- **调用时机**: 设备初始化时自动调用

**示例** (参考 `boards/arcs_evb/pinmux.c`):
​```c
// 代码示例
​```

**注意**:
- 该函数由板型相关代码实现，不同板型的引脚配置可能不同
- 只需配置实际使用的引脚
- 其他注意事项...

### 其他硬件相关配置（可选）

如：支持的通道、参考电压选择、中断触发模式等
```

**要求**:
- 使用二级标题 "硬件配置"
- 必须包含 "引脚复用配置" 三级标题
- 说明 pinmux 函数的定义位置、声明位置、调用时机
- 提供完整的代码示例（参考 arcs_evb 板型）
- 列出注意事项
- 如有其他硬件相关配置（通道、模式等），使用独立的三级标题

### 1.7 详细参数说明（可选，按需添加）

**适用场景**:
- 配置参数复杂（如 ADC 参考电压、UART 配置宏）
- 事件类型多样（如 UART 事件类型）
- 标志位组合（如 GPIO 配置标志）

**格式**:
```markdown
## <参数类型>说明

### <参数分类1>

说明文字或表格

### <参数分类2>

说明文字或表格
```

**要求**:
- 使用二级标题，标题应明确说明参数类型
- 复杂参数优先使用表格展示
- 表格包含：参数名/枚举、说明、示例（如适用）
- 如有组合使用，提供示例代码

**示例**:
```markdown
## 配置标志位

驱动使用标志位方式进行配置，可以通过按位或（`|`）组合多个标志：

### 方向标志
- `LISA_GPIO_INPUT` - 输入模式（默认）
- `LISA_GPIO_OUTPUT` - 输出模式

### 示例组合
​```c
// 输入模式 + 上拉
LISA_GPIO_INPUT | LISA_GPIO_PULL_UP
​```
```

### 1.8 注意事项（必需）

**格式**:
```markdown
## 注意事项

1. **注意点标题**: 详细说明
2. **注意点标题**: 详细说明
...
```

**要求**:
- 使用二级标题 "注意事项"
- 使用有序列表，每项使用 `**粗体**` 突出要点
- 包含但不限于：
  - 使用限制（范围、顺序、前置条件）
  - 常见错误和解决方法
  - 性能影响
  - 线程安全说明
  - 硬件限制
- 按重要性和逻辑关系排序
- 10 条左右为宜，不超过 15 条

**示例**:
```markdown
## 注意事项

1. **必须先配置**: 设备初始化后必须先调用 `lisa_uart_configure()` 配置设备，才能使用功能 API
2. **引脚范围**: 每个 GPIO 控制器支持 0-31 共 32 个引脚
3. **线程安全**: 驱动内部使用互斥锁保护，可在多线程环境中使用
```

### 1.9 文件说明（可选）

**格式**:
```markdown
## 文件说明

- `文件名` - 文件用途说明
- `文件名` - 文件用途说明
```

**要求**:
- 使用二级标题 "文件说明"
- 使用无序列表
- 列出驱动目录下的主要文件
- 简要说明每个文件的用途

## 二、内容编写规范

### 2.1 术语使用

**设备名称**:
- 使用大写：ADC0、GPIOA、UART0
- 示例："支持 UART0、UART1、UART2 三个串口设备"

**API 函数**:
- 使用反引号包裹：`lisa_adc_read()`
- 示例："调用 `lisa_uart_configure()` 配置设备"

**配置项**:
- 使用反引号包裹：`CONFIG_LISA_ADC=y`
- 枚举使用反引号：`LISA_GPIO_INPUT`

**文件路径**:
- 使用反引号包裹：`boards/<板型名>/pinmux.c`
- 使用尖括号表示变量部分：`<板型名>`

### 2.2 代码示例规范

**完整性**:
```c
#include "lisa_xxx.h"  // 必须包含头文件

// 获取设备
lisa_device_t *dev = lisa_device_get_by_name("xxx");
if (!dev) {  // 必须有错误处理
    return -1;
}

// 功能代码
...

// 返回值检查
int ret = lisa_xxx_function(dev, ...);
if (ret == LISA_DEVICE_OK) {
    // 成功处理
}
```

**注释风格**:
- 使用 `//` 单行注释
- 关键步骤添加序号：`// 1. 获取设备`
- 代码后添加说明注释：`return -1;  // 设备未找到`
- 使用中文注释

**错误处理**:
- 设备获取必须检查空指针
- API 调用必须检查返回值
- 简化示例可省略详细错误处理，但需保留结构

### 2.3 表格使用规范

**适用场景**:
- 参数列表（通道、引脚映射）
- 枚举说明（事件类型、配置标志）
- 返回值说明
- 配置选项对比

**格式要求**:
```markdown
| 列标题1 | 列标题2 | 列标题3 |
|--------|--------|--------|
| 内容1  | 内容2  | 内容3  |
```

**内容要求**:
- 表头简洁明确
- 单元格内容简短，避免长句
- 代码使用反引号包裹
- 对齐美观

### 2.4 强调和提示

**粗体强调**:
- 用于标题关键词："**设备支持**: UART0、UART1"
- 用于注意事项："**重要**: 必须先配置设备"

**代码强调**:
- 用于函数名：`lisa_uart_configure()`
- 用于配置项：`CONFIG_LISA_ADC=y`
- 用于枚举：`LISA_GPIO_INPUT`

**重要提示**:
```markdown
**重要**: 说明文字

**注意**: 说明文字
```

### 2.5 语言风格

**简洁明确**:
- 避免冗长描述
- 一句话说清楚一个概念
- 使用主动语态："调用函数配置设备" 而非 "设备通过调用函数被配置"

**专业准确**:
- 使用准确的技术术语
- 避免模糊表述："支持 0-7 通道" 而非 "支持多个通道"
- 数值明确：波特率范围、通道数量

**用户视角**:
- 从使用者角度组织内容
- 先说明"是什么"，再说明"怎么用"
- 提供足够的上下文信息

## 三、章节顺序规范

### 3.1 必需章节（按顺序）

1. 标题与简介
2. 功能特性
3. 配置选项
4. API 接口
5. 使用示例/使用方法
6. 硬件配置
7. 注意事项

### 3.2 可选章节（插入位置）

- **详细 API 说明**：插入在"API 接口"和"使用示例"之间（如果 API 需要详细说明）
- **配置宏/标志位说明**：插入在"API 接口"和"使用示例"之间
- **事件类型说明**：插入在"使用示例"之后，"硬件配置"之前
- **返回值说明**：插入在"硬件配置"之后，"注意事项"之前
- **数据转换/计算**：根据逻辑插入合适位置（如 ADC 的电压转换放在"使用示例"之后）
- **文件说明**：放在文档末尾

### 3.3 章节组织原则

1. 从概念到实践：功能特性 → API → 示例 → 配置
2. 从常用到进阶：基础 API → 进阶功能 → 硬件细节
3. 相关内容靠近：配置参数紧跟配置 API
4. 重要内容前置：常用功能优先介绍

## 四、文档质量检查清单

### 4.1 结构完整性

- [ ] 包含所有必需章节
- [ ] 章节顺序符合规范
- [ ] 标题层级正确（# ## ###）
- [ ] 代码块语言标注正确

### 4.2 内容准确性

- [ ] API 函数原型正确
- [ ] 配置选项有效
- [ ] 代码示例可运行
- [ ] 参数范围准确
- [ ] 返回值说明完整

### 4.3 可读性

- [ ] 术语使用一致
- [ ] 代码注释清晰
- [ ] 表格格式规范
- [ ] 强调使用恰当
- [ ] 无错别字

### 4.4 实用性

- [ ] 提供足够的使用示例
- [ ] 覆盖常见使用场景
- [ ] 包含错误处理示例
- [ ] 注意事项全面
- [ ] 硬件配置说明清晰

## 五、特殊场景处理

### 5.1 复杂 API 的详细说明

当 API 参数复杂或使用有特殊要求时，在"API 接口"章节后添加详细说明：

```markdown
## API 接口

### 配置 ADC 通道

​```c
int lisa_adc_channel_setup(lisa_device_t *dev, uint32_t channel,
                            const lisa_adc_channel_config_t *config);
​```

配置指定通道的参考电压和分辨率。应在读取通道之前调用。

**参数**:
- `dev`: ADC 设备指针
- `channel`: ADC 通道号（0-5：普通通道，6：VBAT，7：TEMP）
- `config`: 通道配置参数，包含：
  - `reference`: 参考电压类型（枚举）
  - `resolution`: ADC 分辨率（枚举）

**返回值**:
- `LISA_DEVICE_OK (0)`: 成功
- `LISA_DEVICE_ERR_INVALID`: 参数无效
```

### 5.2 多设备驱动

当驱动支持多个设备实例时（如 GPIOA/GPIOB、UART0/1/2）：

1. 在"功能特性"中明确列出支持的设备
2. 在"配置选项"中分别列出每个设备的配置项
3. 在"硬件配置"中为每个设备提供独立的 pinmux 示例
4. 在"使用示例"中展示不同设备的使用

### 5.3 特殊功能说明

对于特殊的计算、转换或配置逻辑，使用独立章节说明：

```markdown
## 电压转换

使用 `LISA_ADC_RAW_TO_MV` 宏进行转换：

​```c
uint32_t voltage_mv = LISA_ADC_RAW_TO_MV(raw_value, reference_mv, resolution_bits);
​```

**参数**:
- `raw_value`: ADC 原始采样值
- `reference_mv`: 参考电压（毫伏）
- `resolution_bits`: 分辨率（位数）
```

## 六、版本和维护

### 6.1 文档更新

- 驱动 API 变更时，同步更新文档
- 新增功能时，添加对应示例
- 发现问题时，补充注意事项

### 6.2 示例代码维护

- 确保示例代码与最新 API 保持一致
- 定期验证示例代码的可运行性
- 根据用户反馈改进示例

### 6.3 术语统一

- 维护统一的术语表
- 新驱动文档参考已有文档的术语使用
- 定期审查术语一致性

---

## 附录：快速模板

### A. 基础驱动文档模板

```markdown
# LISA <驱动名称> 驱动

基于 lisa_device 框架的 <设备类型> 设备驱动，为 ARCS 平台提供统一的<功能描述>接口。

## 功能特性

- **设备支持**:
- **核心功能**:
- **配置选项**:
- **线程安全**:

## 配置选项

在 `prj.conf` 中启用驱动：

​```kconfig
CONFIG_LISA_<驱动名称>=y
​```

## API 接口

### 配置接口

​```c
int lisa_xxx_configure();
​```

### 控制接口

​```c
int lisa_xxx_xxx();
​```

## 使用示例

### 基础使用

​```c
#include "lisa_xxx.h"

// 1. 获取设备
lisa_device_t *dev = lisa_device_get_by_name("xxx");
if (!dev) {
    return -1;
}

// 2. 配置设备
// ...

// 3. 使用功能
// ...
​```

## 硬件配置

### 引脚复用配置

<驱动名称> 驱动在初始化时会自动调用板型目录中定义的 `lisa_xxx_pinmux()` 函数。

**配置位置**:
- **定义**: `boards/<板型名>/pinmux.c`
- **声明**: `boards/<板型名>/pinmux.h`
- **调用时机**: 设备初始化时自动调用

**示例**:
​```c
void lisa_xxx_pinmux()
{
    // 配置引脚
}
​```

## 注意事项

1. **使用限制**:
2. **配置要求**:
3. **线程安全**:
```

### B. 参数说明模板

```markdown
## <参数类型>说明

### <参数分类>

| 参数名 | 说明 | 备注 |
|-------|------|------|
| xxx   | xxx  | xxx  |

**示例**:
​```c
// 代码示例
​```
```

---

**本规范基于以下文档分析**:
- drivers/lisa_adc/README.md
- drivers/lisa_gpio/README.md
- drivers/lisa_uart/README.md

**规范版本**: v1.0
**最后更新**: 2025-11-27