版本：v1.0 | 日期：2026-07-03

规定 xt-sdk 的 examples/ 和 tests/ 目录下 README.md 的写法。

一、通用模板

# {名称} {#{dirname}__example_doc}
 
| 平台 | 目标 | 板子 |
|------|------|------|
| {platform} | {target} | {board} |
 
{1-2 句话描述}
 
## 预期行为
 
{具体行为描述，有输出则给出示例日志}
 
## 编译和运行
 
{写的时候把 \` 的转义去掉，这里是因为 doxygen 不支持代码块嵌套}
\`\`\`powershell
cd {目录}
xt --target {平台/目标} fullclean build
xt --target {平台/目标} run
\`\`\`
 
## 故障排除
 
| 现象 | 原因 | 解决 |
|------|------|------|
 
## 注意事项
 
{平台限制、已知问题等}

二、章节说明

章节	必须	说明
标题与标签	必须	标题行末尾带 doxygen 标签，格式见下方《标签命名规则》
支持的平台表格	必须	文件开头紧接标题，只写已验证过的平台和目标
概述	必须	1-2 句话说明做什么
预期行为	必须	描述运行后的表现，有日志则贴真实输出
编译和运行	必须	cd + xt --target 完整命令，命令必须实际验证能通过
故障排除	可选	常见问题和解决方法
注意事项	可选	平台限制、硬件要求、已知问题

2.1 标签命名规则

每个 README.md 标题行末尾必须带 doxygen 页面标签，用于 @subpage 索引：

文档类型	标签格式	示例
示例文档	{#<目录名>__example_doc}	{#adc__example_doc} 、 {#socket-reconnect__example_doc}
测试文档	{#<目录名>__test_doc}	{#xt_event__test_doc} 、 {#xt_vfs_basic__test_doc}

标签写在标题行末尾，{# 前有 ASCII 空格
目录名中的连字符 - 保留不转： {#socket-reconnect__example_doc}
标签只需要出现在**单个示例/测试**的 README 中；分组索引页的标签已在 documentation_guide.md 中定义

三、平台表格规范

3.1 表格列

列	必须	说明
平台	是	windows、linux、lm620、quectel 等
目标	是	simulator、r4f4、r4f2 等。多个目标用 / 分隔，如 r4f4 / r4f2
板子	按需	依赖 xt_board（板级配置）组件时必填。不依赖则不出现此列

3.2 规则

只写验证过的平台和目标 ，不要列不支持的
平台-目标组合格式与编译命令一致（ windows/simulator 、 lm620/r4f4 ）
平台按字母序排列

3.3 示例

纯单元测试（无板子依赖）：

| 平台 | 目标 |
|------|------|
| lm620 | r4f4 |
| windows | simulator |

硬件外设示例（依赖 xt_board）：

| 平台 | 目标 | 板子 |
|------|------|------|
| lm620 | r4f4 | e837n_v01 |

四、测试 README 特殊要求

测试目录的 README 额外要求：

4.1 测试分组表

列出所有 @name 分组及项数：

| 分组 | 测试项数 | 内容 |
|------|---------|------|
| 1. 基本功能 | 11 | setup、subscribe、unsubscribe、publish 等 |
| 2. 边界条件 | 5 | NULL 参数、无效 ID、队列满载 |

4.2 预期行为

描述断言要点，而不是逐项列出测试函数：

## 预期行为
 
- **订阅去重** ：相同 (event_id, callback) 不增加计数
- **重入安全** ：回调中 unsubscribe 立即生效，subscribe 下一轮生效
- **嵌套分发** ：最多 5 层，第 6 层拒绝

4.3 编译运行

## 编译和运行
cd tests/xt_event
xt --target windows/simulator fullclean build
xt --target windows/simulator run

五、示例 README 特殊要求

5.1 描述

必须贴合示例实际行为，不能编造。需要阅读源码后写。

5.2 预期行为

按功能点分小节，有日志输出则贴真实日志：

## 预期行为
 
**LED 输出**：
- NET_LED 和 STATE_LED 以 1 秒间隔交替翻转
 
**输入中断**：
- 下降沿触发时打印电平并累加计数

5.3 硬件示例

硬件相关示例需注明所需硬件和板子：

| 平台 | 目标 | 板子 |
|------|------|------|
| lm620 | r4f4 | e837n_v01 |

5.4 编译运行

windows/simulator 可运行的程序加 run：

cd examples/system/log
xt --target windows/simulator fullclean build
xt --target windows/simulator run

硬件平台不加 run（需下载固件后手动运行）：

cd examples/peripherals/gpio

xt --target lm620/r4f4 --board e837n_v01 fullclean build

六、格式约束

约束	说明
行内标记	** 两侧必须 ASCII 空格，不能紧跟中文标点

七、参考示例

测试 README 范例： tests/xt_event/README.md
外设示例 README 范例： examples/peripherals/gpio/README.md
网络示例 README 范例： examples/network/mobile/README.md