chenyuxuan/arcs

Fork 0

Files

yuuux d1d25a09e7 chore: migrate project into clean repository

2026-08-13 16:50:52 +08:00

34 KiB

Raw Permalink Blame History

ARCS SDK 示例文档编写规范（AI 辅助版）

本规范用于指导 AI 生成和检查 ARCS SDK 示例文档，确保所有示例文档风格统一、信息完整、格式规范。

版本: 2.0 日期: 2025-01-14 维护者: ARCS SDK 团队 适用范围: 所有 samples/ 目录下的示例文档（README.md 或 README.rst）

规范概述

核心原则

结构一致性: 所有示例遵循统一的章节结构和顺序
信息完整性: 必需章节不可缺失，关键信息必须包含
格式统一性: 支持 Markdown 或 reStructuredText 格式，格式内部保持一致
语言规范性: 中英文使用场景明确，术语表达一致

文档格式说明

本规范支持两种文档格式：

Markdown (README.md): 推荐格式，语法简洁，易于编写
reStructuredText (README.rst): 可选格式，适合需要复杂文档结构的场景

两种格式的章节结构和内容要求完全相同，仅语法有所差异。本文档主要以 Markdown 语法为例，RST 格式请参考对应的语法规范。

示例分类

类型	路径	特征	代表示例
设备驱动	`samples/drivers/devices/`	使用 LISA 设备 API，需硬件连接说明	lisa_gpio, lisa_uart
组件模块	`samples/modules/`	系统组件/中间件，可能无硬件依赖	sys_heap, lisa_shell
网络示例	`samples/network/`	网络协议/通信，需环境配置	http, wifi_manager
HAL 驱动	`samples/drivers/hal/`	底层硬件抽象层，需硬件连接	gpio, uart, spi

文档结构规范

标准章节结构（按顺序）

必需章节（所有示例）

序号	章节	标题格式	必需性	适用范围
1	标题	`# {模块名} {功能}示例`	✅ 必需	所有
2	功能说明	`## 功能说明`	✅ 必需	所有
3	硬件连接	`## 硬件连接`	✅ 必需	所有
4	示例内容/步骤	`## 示例内容` 或 `## 示例步骤`	✅ 必需	所有
5	编译	`## 编译`	✅ 必需	所有
6	烧录	`## 烧录`	✅ 必需	所有
7	预期输出	`## 预期输出`	✅ 必需	所有
8	核心 API	`## 核心 API`	⭐ 强烈推荐	Devices, Modules
9	关键代码	`## 关键代码`	⭐ 强烈推荐	所有
10	注意事项	`## 注意事项`	⭐ 强烈推荐	所有

可选章节（根据需要）

章节	标题格式	使用场景
新特性	`### 新特性`	高级示例，展示技术优势
使用场景	`## 使用场景`	需说明技术选型时
配置说明	`## 配置说明`	有重要配置参数时
功能详解	`## {功能}说明`	需解释工作原理时
验证方法	`## 验证方法`	输出不可直接观察时
测试环境	`## 测试环境准备`	需复杂环境配置时

章节顺序规则

固定顺序（不可调整）:

1. 标题（H1）
2. 功能说明（H2）
   └── 新特性（H3，可选）
3. 硬件连接（H2）
4. 使用场景/测试环境（H2，可选）
5. 示例内容/步骤（H2）
6. 编译（H2）
7. 烧录（H2）
8. 预期输出（H2）
9. 核心 API（H2，推荐）
10. 功能详解（H2，可选）
11. 关键代码（H2，推荐）
12. 配置说明（H2，可选）
13. 验证方法（H2，可选）
14. 注意事项（H2，推荐）
15. 相关文档（H2，可选）

各章节详细规范

1. 标题（H1）

格式模式:

# {模块名称} {功能描述}示例{（可选说明）}

规则:

模块名称: 使用正式名称（LISA GPIO、系统堆管理、HTTP 客户端）
功能描述: 简洁明了（基础输出、内存分配、同步接收）
可选说明: 括号中注明特殊模式（DMA 模式、中断模式）

正确示例:

✅ # LISA GPIO 基础输出示例
✅ # 系统堆管理基础示例
✅ # LISA UART 同步接收示例（DMA 模式）
✅ # HTTP 客户端基础示例

错误示例:

❌ # gpio example (未使用中文，未规范化模块名)
❌ # LISA_GPIO 基础示例 (模块名使用下划线)
❌ # GPIO 示例 (缺少 LISA 前缀)

2. 功能说明（H2，必需）

格式:

## 功能说明

{第一段：核心功能说明（1-2 句话）}

{第二段：可选补充说明（技术特点/底层实现）}

内容要求:

第一段（必需）:
- 1-2 句话说明核心功能
- 40-200 字为宜
- 说明"做什么"和"怎么做"
第二段（可选）:
- 补充技术特点或实现细节
- 突出技术优势或注意事项

正确示例:

## 功能说明

演示如何使用 LISA GPIO 驱动控制 LED 闪烁，通过配置引脚为输出模式，周期性输出高低电平实现 LED 的亮灭切换。

## 功能说明

演示如何使用系统堆管理组件分配和释放内存，包括内部 SRAM 和外部 PSRAM 的基本操作。

## 功能说明

此示例演示如何使用 LISA HTTP 客户端库进行基本的 HTTP 通信，包括：
- HTTP GET 请求
- HTTP POST 请求（普通表单数据）
- HTTP POST 请求（Chunked 传输编码）

示例通过 WiFi 连接到测试服务器，执行多个 HTTP 请求并接收响应，展示了 HTTP 客户端的基本用法。

错误示例:

❌ ## 功能说明

This example shows... (使用英文)

❌ ## 功能说明

本示例功能强大，非常好用，可以实现各种复杂的操作... (描述过于笼统，未说明具体功能)

3. 新特性（H3，可选）

使用时机:

高级示例（DMA、中断、异步等）
有明显技术优势需要突出
与基础示例有显著差异

格式:

### 新特性

- **特性1**: 简短说明
- **特性2**: 简短说明
- **特性3**: 简短说明

内容要求:

使用无序列表
每项开头用粗体标注特性名称
3-5 项为宜
每项一行，简洁明了

正确示例:

### 新特性

- **DMA 硬件传输**: 无需 CPU 参与数据搬移，降低 CPU 占用
- **异步非阻塞**: 调用后立即返回，DMA 后台传输
- **事件回调通知**: 传输完成后通过中断回调通知应用层
- **适合高速率场景**: 支持高波特率连续发送，不阻塞主任务

4. 硬件连接（H2，必需）

格式（有外部连接）:

## 硬件连接

- **引脚编号**: 功能说明
- **引脚编号**: 功能说明

{补充说明（可选）}

格式（无外部连接）:

## 硬件连接

无需外部连接，{模块}为芯片内部资源。

内容要求:

引脚说明:
- 使用无序列表
- 引脚编号用粗体
- 说明引脚功能和用途
补充说明:
- 连接方式、配置参数
- 外部设备要求
- 硬件注意事项

正确示例（有连接）:

## 硬件连接

- **PB09**: LED 控制引脚（外接 LED 与限流电阻，ARCS-EVB 板载接口）

将 LED 正极（长脚）通过限流电阻（推荐 220Ω-1kΩ）连接到 PB09 引脚，负极（短脚）连接到 GND。

## 硬件连接

- **PA2**: UART0 RX（接收）
- **PA3**: UART0 TX（发送）

连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**

正确示例（无连接）:

## 硬件连接

无需外部连接，系统堆为芯片内部资源。

## 硬件连接

本示例使用芯片内部 WiFi 外设，无需额外接线。

**串口输出：**
- 串口 TX: PA3
- 波特率：921600

5. 示例内容/步骤（H2，必需）

标题选择:

## 示例内容: 用于功能演示类示例
## 示例步骤: 用于操作流程类示例

格式:

## 示例内容

1. 步骤1描述
2. 步骤2描述
3. 步骤3描述
4. 步骤4描述

内容要求:

使用有序列表（编号列表）
3-6 个步骤为宜
每步简洁明了，突出关键操作
按执行顺序排列

正确示例:

## 示例内容

1. 从内部 SRAM 分配 256 字节内存
2. 从外部 PSRAM 分配 1024 字节内存
3. 使用 `psram_calloc()` 分配并清零内存
4. 使用 `psram_realloc()` 重新分配内存
5. 查看堆使用统计信息

## 示例步骤

1. 获取 GPIOB 设备
2. 配置 PB09 引脚为输出模式，初始电平为低
3. 循环切换引脚输出电平（高/低）
4. 每次切换间隔 1 秒，实现 LED 闪烁效果

6. 编译/运行（H2，必需）

标题选择:

## 编译: 仅说明编译（推荐）
## 编译运行: 包含编译和运行
## 编译 + 独立 ## 烧录: 编译和烧录分开（推荐）

推荐格式（使用 RST 引用）:

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

## 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

说明:

统一使用 RST 引用文件，保持格式一致性
/sample_build.rst 包含标准编译命令
/sample_flash.rst 包含标准烧录命令
分开成两个独立的 H2 章节（## 编译 和 ## 烧录）

备选格式（直接写命令）:

如果需要特殊的编译参数或说明，可以直接写命令：

## 编译

```bash
./build.sh -C -DBOARD=arcs_evb
```

## 烧录

```bash
./build.sh -F
```

合并格式（不推荐）:

## 编译运行

### 编译

```{eval-rst}
.. include:: /sample_build.rst
```

### 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

注意:

优先使用 RST 引用格式，除非有特殊说明需要
编译和烧录建议分为两个独立的 H2 章节，而不是使用 H3 子章节

7. 预期输出（H2，必需）

格式（单一输出源）:

## 预期输出

```
[I][sample] === Example Output ===
...
```

格式（多个输出源）:

## 预期输出

**终端输出：**
```
[I][sample] === Example Output ===
...
```

**串口工具接收：**
```
Hello World
...
```

**LED 状态：**
- LED 每秒切换一次亮灭状态

内容要求:

真实输出: 必须与实际运行结果一致
完整性: 包含关键日志，可用 ... 省略重复部分
格式: 使用代码块，保持原始格式
分类: 多个输出源用 粗体标题 分隔

正确示例:

## 预期输出

**终端输出：**
```
=== LISA GPIO output example ===
gpiob device ready
Start toggling LED...
LED is ON
LED is OFF
LED is ON
LED is OFF
...
```

**LED 状态：**
- LED 每秒切换一次亮灭状态
- 亮时对应高电平输出，灭时对应低电平输出

8. 核心 API（H2，强烈推荐）

使用场景:

设备驱动示例（Devices）
组件模块示例（Modules）
有明确 API 调用的示例

格式:

## 核心 API

| API | 说明 |
|-----|------|
| `api_function_1()` | 功能说明1 |
| `api_function_2()` | 功能说明2 |
| `api_function_3()` | 功能说明3 |

内容要求:

使用表格: 固定两列格式
API 名称: 使用反引号 包裹，保留括号 ()`
顺序: 按调用顺序排列
数量: 3-8 个关键 API
说明: 简洁准确，动词开头

正确示例:

## 核心 API

| API | 说明 |
|-----|------|
| `lisa_device_get()` | 获取 GPIO 设备 |
| `lisa_device_ready()` | 检查设备是否就绪 |
| `lisa_gpio_configure()` | 配置 GPIO 引脚模式和属性 |
| `lisa_gpio_write_pin()` | 设置 GPIO 引脚输出电平 |

## 核心 API

| API | 说明 |
|-----|------|
| `inram_malloc()` | 从内部 SRAM 分配内存 |
| `inram_free()` | 释放内部 SRAM 内存 |
| `psram_malloc()` | 从 PSRAM 分配内存 |
| `psram_calloc()` | 从 PSRAM 分配并清零内存 |
| `psram_realloc()` | 重新分配 PSRAM 内存 |
| `psram_free()` | 释放 PSRAM 内存 |
| `heap_summary_info()` | 打印堆统计信息 |

9. 关键代码（H2，强烈推荐）

使用场景:

有重要配置或技巧需要展示
代码包含关键 API 调用序列
需要解释复杂代码逻辑

格式:

## 关键代码

```c
/* 注释说明 */
code_block();

/* 注释说明 */
another_code_block();
```

内容要求:

语言标注: 必须指定 c
注释: 关键代码添加中文注释
完整性: 代码片段可独立理解
简洁性: 省略无关代码，突出重点

正确示例:

## 关键代码

```c
/* 配置为输出模式，初始电平为低 */
int ret = lisa_gpio_configure(gpio_dev, LED_PIN,
                              LISA_GPIO_OUTPUT | LISA_GPIO_OUTPUT_INIT_LOW);

/* 循环切换 LED 状态 */
bool led_on = true;
while (1) {
    lisa_gpio_write_pin(gpio_dev, LED_PIN,
                        led_on ? LISA_GPIO_HIGH : LISA_GPIO_LOW);
    LISA_LOGI(LOG_TAG, "LED is %s", led_on ? "ON" : "OFF");
    vTaskDelay(pdMS_TO_TICKS(1000));
    led_on = !led_on;
}
```

10. 配置说明（H2，可选）

使用场景:

有重要配置参数
配置有特殊要求或限制
Kconfig 配置项说明

格式:

## 配置说明

### 配置项1名称

{说明内容}

- **配置1**: 说明
- **配置2**: 说明

### 配置项2名称

{说明内容}

正确示例:

## 配置说明

### 堆大小配置

在 Kconfig 中可配置堆大小（组件默认已配置）：

- **`CONFIG_HEAP_SIZE`**: 内部 SRAM 堆大小，默认 0x5000 (20KB)
- **`CONFIG_PSRAM_HEAP_SIZE`**: PSRAM 堆大小，默认 0x20000 (128KB)

### 对齐要求

- **`inram_malloc(align, size)`**: `align` 参数指定对齐字节数，必须是 2 的幂次方（4, 8, 16, 32 等）
- **`psram_malloc(size)`**: 默认 4 字节对齐
- **`psram_malloc_align(align, size)`**: 指定对齐字节数，用于 DMA 等需要特定对齐的场景

11. 注意事项（H2，强烈推荐）

使用场景:

所有示例都应包含
有重要限制或约束
常见错误提醒

格式:

## 注意事项

1. **关键词1**: 详细说明
2. **关键词2**: 详细说明
3. **关键词3**: 详细说明

内容要求:

使用有序列表
关键词粗体: 每项开头用粗体标注关键词
数量: 3-5 项为宜
内容: 安全、限制、易错点、最佳实践

正确示例:

## 注意事项

1. **返回值检查**: 分配内存后务必检查返回值是否为 NULL，防止使用无效指针
2. **内存释放**: 使用完毕后及时释放内存，避免内存泄漏
3. **对齐参数**: `align` 参数必须是 2 的幂次方，否则会导致对齐错误
4. **自动初始化**: 系统堆在 main 函数前自动初始化，无需手动调用
5. **线程安全**: 所有堆分配接口都是线程安全的，可在多任务环境下使用

不同类型示例的差异

Devices（设备驱动示例）

特征:

使用 LISA 设备驱动 API
必需硬件连接说明
强调引脚配置和参数

必需章节:

✅ 硬件连接（详细引脚说明）
✅ 核心 API（LISA 设备 API）
✅ 注意事项（硬件相关限制）

可选章节:

配置说明（参数配置）
验证方法（硬件验证）

示例: lisa_gpio/output_basic

Modules（组件模块示例）

特征:

系统组件/中间件
可能无硬件依赖
注重 API 使用方法

必需章节:

✅ 功能说明（详细功能说明）
✅ 核心 API（组件 API）
✅ 关键代码（使用示例）

可选章节:

配置说明（Kconfig 配置）
使用场景（应用场景）

示例: modules/sys_heap, modules/lisa_shell

Network（网络示例）

特征:

涉及网络协议
需要环境配置
包含连接建立过程

必需章节:

✅ 功能说明（网络功能）
✅ 测试环境准备（环境配置）
✅ 预期输出（网络交互日志）

可选章节:

核心 API（网络 API）
配置说明（网络参数）

示例: network/http

HAL（硬件抽象层示例）

特征:

底层硬件接口
使用表情符号标题（历史原因）
简洁实用

必需章节:

✅ 📖示例说明（功能说明）
✅ 硬件连接
✅ 预期输出

特殊规则:

可使用 📖示例说明 替代 功能说明
通常不包含核心 API 章节

格式规范

文档格式选择

Markdown 格式 (README.md) - 推荐

优点:

语法简洁，易于学习和编写
GitHub/GitLab 原生支持预览
工具链完善

适用场景:

大部分示例文档
结构简单的文档

reStructuredText 格式 (README.rst) - 可选

优点:

功能强大，支持复杂文档结构
Sphinx 文档系统原生格式
适合技术文档

适用场景:

需要复杂表格或指令的文档
需要与 Sphinx 文档系统集成

选择建议: 优先使用 Markdown，除非有特殊需求。

Markdown 语法规范

1. 标题层级

# H1 - 文档标题（只能有一个）
## H2 - 主要章节
### H3 - 子章节
#### H4 - 更小的子章节（慎用）

规则:

H1 只能有一个（文档标题）
H2 用于主要章节
H3 用于子章节（如"新特性"、配置项）
避免使用 H4 及以下层级

RST 等价语法

标题（H1）
=========

章节（H2）
---------

子章节（H3）
^^^^^^^^^^^

2. 代码块

Markdown 格式:

```c
// C 代码
```

```bash
# Bash 命令
```

```
纯文本输出
```

RST 格式:

.. code-block:: c

   // C 代码

.. code-block:: bash

   # Bash 命令

.. code-block:: text

   纯文本输出

语言标注要求:

c: C 语言代码
bash: Shell 命令
text (RST) 或无标注 (Markdown): 纯文本输出

3. 行内代码标记

Markdown 格式:

使用 `lisa_gpio_configure()` 配置引脚。
配置项 `CONFIG_HEAP_SIZE` 的默认值是 0x5000。
变量 `gpio_dev` 保存设备句柄。

RST 格式:

使用 ``lisa_gpio_configure()`` 配置引脚。
配置项 ``CONFIG_HEAP_SIZE`` 的默认值是 0x5000。
变量 ``gpio_dev`` 保存设备句柄。

规则:

API 函数名保留括号: function() (Markdown) 或 function() (RST)
配置项宏定义: CONFIG_NAME
变量名: variable_name

4. 粗体使用

关键概念、重要信息:

- **返回值检查**: 务必检查返回值
- **内存对齐**: 必须 **32 字节对齐**
连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**

规则:

注意事项的关键词
重要参数值
强调的概念

5. 表格格式

Markdown 格式:

| 列1标题 | 列2标题 |
|---------|---------|
| 内容1   | 说明1   |
| 内容2   | 说明2   |

RST 格式:

.. list-table::
   :header-rows: 1

   * - 列1标题
     - 列2标题
   * - 内容1
     - 说明1
   * - 内容2
     - 说明2

规则:

Markdown: 使用对齐的 | 分隔符，第二行用 - 分隔标题和内容
RST: 使用 .. list-table:: 指令，:header-rows: 1 指定标题行
API 表格固定格式: | API | 说明 | (Markdown) 或对应的 RST list-table

6. 列表格式

有序列表（步骤、注意事项）:

1. 第一步
2. 第二步
3. 第三步

无序列表（特性、引脚、配置）:

- 项目1
- 项目2
- 项目3

子列表（2 空格缩进）:

- 父项目
  - 子项目1
  - 子项目2

语言规范

1. 中英文使用规则

位置	语言	示例
文档正文	中文	演示如何使用...
代码注释	中文	`/* 配置引脚为输出模式 */`
API 名称	英文	`lisa_gpio_configure()`
配置项	英文	`CONFIG_HEAP_SIZE`
日志输出	英文	`LISA_LOGI(LOG_TAG, "Device ready");`
代码变量	英文	`uint8_t *buffer;`

2. 术语标准表达

模块名称:

✅ LISA GPIO（正确）
❌ lisa_gpio, GPIO, lisa gpio（错误）

技术术语:

✅ DMA 模式（正确）
❌ dma 模式, Dma 模式（错误）
✅ 中断模式（正确）
❌ INT 模式, interrupt 模式（错误）
✅ 同步/异步（正确）
❌ sync/async（仅在代码中使用）

一致性原则:

同一概念在整篇文档中必须使用统一术语，不能混用。

3. 中英文混排

规则:

中英文之间通常不加空格（除非是完整英文句子）。

示例:

✅ 使用`lisa_gpio_configure()`配置引脚为输出模式。
✅ 使用 `lisa_gpio_configure()` 配置引脚为输出模式。
✅ 配置项`CONFIG_HEAP_SIZE`的默认值是 0x5000。

AI 生成文档指南

生成流程

当 AI 收到"生成示例文档"的任务时，按以下流程操作：

第一步：确定示例类型

问题：这是哪种类型的示例？
选项：
- Devices（设备驱动）
- Modules（组件模块）
- Network（网络示例）
- HAL（硬件抽象层）

第二步：确定复杂度

问题：这是基础示例还是高级示例？
- 基础示例：使用基础模板，包含必需章节
- 高级示例：使用高级模板，增加"新特性"、"使用场景"等章节

第三步：收集信息

收集以下信息：
1. 模块名称（如：LISA GPIO、系统堆管理）
2. 功能描述（如：基础输出、内存分配）
3. 硬件连接（引脚信息或"无需外部连接"）
4. 示例步骤（3-6 个关键步骤）
5. 核心 API（3-8 个关键 API 及说明）
6. 预期输出（实际日志或输出描述）
7. 注意事项（3-5 个关键限制或提醒）

第四步：选择模板

根据类型和复杂度选择合适模板：

基础示例模板：
- 标题
- 功能说明
- 硬件连接
- 示例内容
- 编译（使用 RST 引用）
- 烧录（使用 RST 引用）
- 预期输出
- 核心 API
- 关键代码
- 注意事项

高级示例模板：
- 标题
- 功能说明
  - 新特性（H3）
- 硬件连接
- 使用场景
- 示例步骤
- 编译（使用 RST 引用）
- 烧录（使用 RST 引用）
- 预期输出
- 核心 API
- 功能详解
- 关键代码
- 配置说明
- 注意事项

第五步：填充内容

按模板顺序填充各章节，确保：

标题格式正确: # {模块} {功能}示例
功能说明简洁: 1-2 句话
硬件连接完整: 引脚信息或明确说明"无需外部连接"
步骤清晰有序: 使用有序列表
编译和烧录: 使用 RST 引用格式（.. include:: /sample_build.rst 和 .. include:: /sample_flash.rst）
API 表格规范: 使用标准表格格式
代码块标注语言: c、bash 或无标注
注意事项完整: 3-5 项，关键词粗体

第六步：自检

生成后对照"AI 审查文档清单"自检。

生成示例模板

基础示例模板

# {模块名称} {功能描述}示例

## 功能说明

{1-2 句话说明核心功能}

## 硬件连接

- **引脚1**: 功能说明
- **引脚2**: 功能说明

或：

无需外部连接，{模块}为芯片内部资源。

## 示例内容

1. 步骤1
2. 步骤2
3. 步骤3
4. 步骤4

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

## 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

## 预期输出

```
[I][sample] === Example Output ===
{实际输出内容}
```

## 核心 API

| API | 说明 |
|-----|------|
| `api_1()` | 功能说明1 |
| `api_2()` | 功能说明2 |
| `api_3()` | 功能说明3 |

## 关键代码

```c
/* 关键代码片段 */
code_example();
```

## 注意事项

1. **关键词1**: 说明
2. **关键词2**: 说明
3. **关键词3**: 说明

高级示例模板

# {模块名称} {功能描述}示例（{模式说明}）

## 功能说明

{1-2 句话说明核心功能}

### 新特性

- **特性1**: 说明
- **特性2**: 说明
- **特性3**: 说明

## 硬件连接

- **引脚1**: 功能说明
- **引脚2**: 功能说明

{补充连接说明}

## 使用场景

{适用场景和技术选型说明}

## 示例步骤

1. 步骤1
2. 步骤2
3. 步骤3
4. 步骤4

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

## 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

## 预期输出

**终端输出：**
```
[I][sample] === Example Output ===
{输出内容}
```

**{其他输出源}：**
{描述}

## 核心 API

| API | 说明 |
|-----|------|
| `api_1()` | 功能说明1 |
| `api_2()` | 功能说明2 |
| `api_3()` | 功能说明3 |

## {功能}说明

{详细说明工作原理和特性}

## 关键代码

```c
/* 关键代码片段 */
code_example();
```

## 配置说明

### 配置项1

{说明}

### 配置项2

{说明}

## 注意事项

1. **关键词1**: 说明
2. **关键词2**: 说明
3. **关键词3**: 说明
4. **关键词4**: 说明

AI 审查文档清单

当 AI 收到"检查示例文档"的任务时，使用以下清单逐项检查：

结构检查

□ 标题（H1）存在且格式正确
□ 功能说明（H2）存在且简洁（1-2 句话，40-200 字）
□ 硬件连接（H2）存在且完整（有引脚信息或明确说明无需连接）
□ 示例内容/步骤（H2）存在且使用有序列表
□ 编译（H2）存在且使用 RST 引用（推荐）或包含构建命令
□ 烧录（H2）存在且使用 RST 引用（推荐）或包含烧录命令
□ 预期输出（H2）存在且非空
□ 核心 API（H2）存在（Devices/Modules 类型）
□ 注意事项（H2）存在且有 3-5 项
□ 章节顺序符合规范

格式检查

□ 文档格式正确（Markdown .md 或 RST .rst）
□ 所有代码块指定了语言（c/bash/text）
□ 编译和烧录使用引用格式（Markdown 用 eval-rst，RST 用 include 指令）
□ API 名称使用正确标记（Markdown 用 `，RST 用 ``）
□ 核心 API 使用标准表格格式（Markdown 表格或 RST list-table）
□ 注意事项使用有序列表，关键词用粗体（Markdown **粗体**，RST **粗体**）
□ 引脚编号用粗体（Markdown **PB09**，RST **PB09**）
□ 中英文混排符合规范
□ 无过深层级标题（避免 H4/H5 或 RST 过多下划线层级）
□ 编译和烧录为独立章节（不使用子章节）
□ 格式内部保持一致（不混用 Markdown 和 RST 语法）

内容检查

□ 标题格式：{模块} {功能}示例
□ 功能说明不超过 200 字
□ 硬件连接有具体引脚或明确说明无需连接
□ 示例步骤有 3-6 项
□ 预期输出与代码一致（如果有源代码）
□ API 表格有 3-8 项，按调用顺序排列
□ 注意事项包含重要限制和易错点
□ 术语使用一致（如：DMA 模式，不是 dma 模式）

语言检查

□ 文档正文使用中文
□ API 名称使用英文
□ 代码注释使用中文
□ 日志输出使用英文
□ 术语表达标准化（LISA GPIO、DMA 模式、中断模式）
□ 同一概念术语统一，无混用

类型特定检查

Devices（设备驱动）:

□ 标题使用 LISA 前缀（如：LISA GPIO）
□ 硬件连接详细（引脚编号、功能、接线方式）
□ 核心 API 包含 lisa_device_get() 等设备 API
□ 注意事项包含硬件相关限制

Modules（组件模块）:

□ 功能说明详细说明组件功能
□ 硬件连接说明"无需外部连接"（如适用）
□ 核心 API 包含组件关键 API
□ 可选：配置说明章节（Kconfig）

Network（网络示例）:

□ 功能说明包含网络协议/功能
□ 可选：测试环境准备章节
□ 预期输出包含网络交互日志
□ 注意事项包含网络环境要求

审查报告格式

AI 检查后应输出以下格式的报告：

# 文档审查报告

**文档路径**: {文件路径}
**示例类型**: {Devices/Modules/Network/HAL}
**审查日期**: {日期}

## 审查结果

**总体评分**: {通过/需修改/不合格}

## 问题清单

### 必需修改（阻塞问题）

1. **[结构]** {问题描述}
   - **位置**: {章节名称}
   - **问题**: {具体问题}
   - **建议**: {修改建议}

2. **[格式]** {问题描述}
   - **位置**: {章节名称/行号}
   - **问题**: {具体问题}
   - **建议**: {修改建议}

### 建议优化（非阻塞）

1. **[内容]** {问题描述}
   - **位置**: {章节名称}
   - **建议**: {优化建议}

## 符合规范项

✅ 标题格式正确
✅ 功能说明简洁
✅ 章节顺序符合规范
...

## 总结

{总体评价和建议}

附录

附录 A：常见问题

Q1: 何时使用"示例内容"vs"示例步骤"？

示例内容: 用于功能演示类示例，列出演示的功能点
示例步骤: 用于操作流程类示例，列出执行的步骤

示例：

## 示例内容（功能演示）
1. 从内部 SRAM 分配内存
2. 从外部 PSRAM 分配内存
3. 使用 calloc 分配并清零内存

## 示例步骤（操作流程）
1. 获取 UART 设备
2. 配置 UART 参数
3. 发送数据并等待完成

Q2: 何时添加"新特性"章节？

高级示例（DMA、中断、异步等）
有明显技术优势需要突出
与基础示例有显著差异

Q3: 硬件连接章节可以省略吗？

A: 不可以。所有示例都必须包含硬件连接章节，即使无需外部连接，也应明确说明"无需外部连接，{模块}为芯片内部资源"。

Q4: 预期输出必须包含实际日志吗？

A: 是的。预期输出必须与实际运行结果一致。如果输出很长，可以使用 ... 省略重复部分，但关键日志必须包含。

Q5: 核心 API 章节是必需的吗？

A: 强烈推荐，特别是 Devices 和 Modules 类型示例。Network 和 HAL 类型可根据情况选择。

附录 B：术语对照表

中文术语	英文术语	使用场景
设备驱动	Device Driver	文档正文
组件模块	Module	文档正文
引脚	Pin	硬件连接
中断模式	Interrupt Mode	功能说明
DMA 模式	DMA Mode	功能说明
同步发送	Synchronous Send	功能说明
异步发送	Asynchronous Send	功能说明
循环缓冲区	Circular Buffer	技术说明
串口工具	Serial Tool	硬件连接
波特率	Baud Rate	配置说明
占空比	Duty Cycle	PWM 相关
内存对齐	Memory Alignment	配置说明

附录 C：Markdown 与 RST 格式对照

基本语法对照表

元素	Markdown	RST
H1 标题	`# 标题`	`标题\n====`
H2 标题	`## 标题`	`标题\n----`
H3 标题	`### 标题`	`标题\n^^^^`
行内代码	`code`	``code``
代码块	```c\ncode\n```	`.. code-block:: c\n\n code`
粗体	`粗体`	`粗体`
链接	`[text](url)`	`text <url>`_
表格	Markdown table	`.. list-table::`
Include	`{eval-rst}\n.. include::`	`.. include::`

完整示例对照

Markdown 版本:

# LISA GPIO 基础输出示例

## 功能说明

演示如何使用 `lisa_gpio_configure()` 配置引脚。

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

## 核心 API

| API | 说明 |
|-----|------|
| `lisa_device_get()` | 获取设备 |

RST 版本:

LISA GPIO 基础输出示例
======================

功能说明
--------

演示如何使用 ``lisa_gpio_configure()`` 配置引脚。

.. include:: /sample_build.rst

核心 API
--------

.. list-table::
   :header-rows: 1

   * - API
     - 说明
   * - ``lisa_device_get()``
     - 获取设备

附录 D：示例文档索引

优秀示例文档（推荐参考）:

Devices (Markdown):
- samples/drivers/devices/lisa_gpio/output_basic/README.md
- samples/drivers/devices/lisa_uart/send_async_dma/README.md
Modules (Markdown):
- samples/modules/sys_heap/README.md
- samples/modules/lisa_shell/README.md
Network (Markdown):
- samples/network/http/README.md
Basic (RST):
- samples/helloworld/README.rst

附录 E：版本历史

版本	日期	变更说明
1.0	2025-01-15	初始版本（Samples_Spec.md）
2.0	2025-01-14	AI 辅助版，基于 114 个示例文档分析
2.1	2025-01-14	支持 Markdown 和 RST 两种格式

主要变更（2.1）:

支持双格式: 允许使用 Markdown (.md) 或 reStructuredText (.rst)
格式对照: 新增附录 C - Markdown 与 RST 格式对照表
审查清单更新: 格式检查项适配双格式要求
语法规范: 补充 RST 格式的等价语法说明
示例索引: 新增 RST 格式示例文档引用

主要变更（2.0）:

基于实际分析数据（114 个 README.md）
明确不同类型示例的差异和特殊规则
新增 AI 生成文档指南
新增 AI 审查文档清单
详细格式规范和示例
新增常见问题和术语对照表

维护者: ARCS SDK 团队 联系方式: sdk@listenai.com 最后更新: 2025-01-14

34 KiB Raw Permalink Blame History Unescape Escape

ARCS SDK 示例文档编写规范（AI 辅助版）

目录

规范概述

核心原则

文档格式说明

示例分类

文档结构规范

标准章节结构（按顺序）

必需章节（所有示例）

可选章节（根据需要）

章节顺序规则

各章节详细规范

1. 标题（H1）

2. 功能说明（H2，必需）

3. 新特性（H3，可选）

4. 硬件连接（H2，必需）

5. 示例内容/步骤（H2，必需）

6. 编译/运行（H2，必需）

7. 预期输出（H2，必需）

8. 核心 API（H2，强烈推荐）

9. 关键代码（H2，强烈推荐）

10. 配置说明（H2，可选）

11. 注意事项（H2，强烈推荐）

不同类型示例的差异

Devices（设备驱动示例）

Modules（组件模块示例）

Network（网络示例）

HAL（硬件抽象层示例）

格式规范

文档格式选择

Markdown 格式 (README.md) - 推荐

reStructuredText 格式 (README.rst) - 可选

Markdown 语法规范

1. 标题层级

RST 等价语法

2. 代码块

3. 行内代码标记

4. 粗体使用

5. 表格格式

6. 列表格式

语言规范

1. 中英文使用规则

2. 术语标准表达

3. 中英文混排

AI 生成文档指南

生成流程

第一步：确定示例类型

第二步：确定复杂度

第三步：收集信息

第四步：选择模板

第五步：填充内容

第六步：自检

生成示例模板

基础示例模板

高级示例模板

AI 审查文档清单

结构检查

格式检查

内容检查

语言检查

类型特定检查

审查报告格式

附录

附录 A：常见问题

Q1: 何时使用"示例内容"vs"示例步骤"？

Q2: 何时添加"新特性"章节？

Q3: 硬件连接章节可以省略吗？

Q4: 预期输出必须包含实际日志吗？

Q5: 核心 API 章节是必需的吗？

附录 B：术语对照表

附录 C：Markdown 与 RST 格式对照

基本语法对照表

完整示例对照

附录 D：示例文档索引

附录 E：版本历史

34 KiB

Raw Permalink Blame History