文档编写指南

本指南规定 xt-sdk 文档系统的组织方式、命名规范、链接规范和新增流程。所有新增/修改文档必须遵循本指南。

---

一、文档树

1.1 就近组织原则

文档 放在它描述的代码附近 ：

• 每个有子文档的目录都有 README.md 作为目录索引
• 模块文档放在模块目录内（如 components/xt_vfs/README.md）
• 规范文档放在 docs/dev_guide/ 下
• README.md 只管当前目录的直接子文档 ，不跨级展开

1.2 README.md 的两种角色

目录类型	README.md 角色	标签后缀	示例
单模块目录	README.md 就是模块文档	__doc	components/xt_vfs/README.md
多模块目录	README.md 是纯索引页，各模块单独 .md	__sum_doc	components/xt_task/README.md

---

二、页面标签命名规范

2.1 标签格式

所有 doxygen 页面标签用 双下划线 作为类型分隔符：

标签类型	格式	示例
模块文档	{组件名}__doc	{#xt_vfs__doc}
多模块索引页	{目录名}__sum_doc	{#xt_task__sum_doc}
测试文档	{模块名}__tests_doc	{#xt_vfs__tests_doc}
开发者 API 分组（@defgroup）	{组件名}__dev	\@defgroup 开发者接口
主页	{#mainpage}	doxygen 特殊识别

2.2 声明方式

用 markdown 原生语法，不用 @page 命令：

# xt_vfs 虚拟文件系统模块 {#xt_vfs__doc}

前提：Doxyfile 中 IMPLICIT_DIR_DOCS = NO。

2.3 为什么用双下划线

单下划线 _dev 与 C 标识符冲突（device 缩写也是 _dev）。

---

三、链接规范

3.1 索引页：@subpage + markdown 双链接

索引页（README.md）引用子文档时，表格内用双链接：

| @subpage xt_vfs__doc ([xt_vfs](./xt_vfs/README.md)) | 虚拟文件系统 |

• \@subpage 标签名：建立 doxygen 页面层级 + 页面内链接（显示页面标题）
• ([显示名](相对路径))：markdown 阅读器的可点击链接
• @subpage 和 ( 之间必须留空格

3.2 正文引用

正文中引用其他页面或 API 实体时用 @ref：

详见 @ref xt_vfs__doc 。
完整的函数签名请查看 @ref xt_vfs 。
调用 @ref xt_vfs_init 初始化。

3.3 相对路径注意事项

路径格式	doxygen 行为	建议
./xxx（同目录/子目录）	正确解析	推荐
../xxx（父目录）	相对于项目根目录解析，通常错误	避免 ，改用 @ref

3.4 禁止的链接写法

以下写法会导致 doxygen 生成错误链接或空页面：

❌ @subpage md__d_1_2work_2pt_2..._xt__vfs   （用了本地绝对路径）
❌ [文字](group__xt__vfs.html)                 （用了生成的 HTML 文件名）
❌ [文字](xt_vfs.md)                            （跨目录文件名链接，会生成空页面）

正确做法：用 \@subpage 标签名 或 \@ref 标签名，标签名是 {#标签} 中声明的名字。

---

四、doxygen 配置要点

4.1 关键配置项

配置项	值	原因
IMPLICIT_DIR_DOCS	NO	子目录 README.md 作为普通页面，# 标题 {#标签} 生效
USE_MDFILE_AS_MAINPAGE	../mainpage.md	根目录 mainpage.md 作为首页
MARKDOWN_SUPPORT	YES	启用 markdown 支持
GENERATE_TREEVIEW	YES	生成左侧导航树
HTML_DYNAMIC_SECTIONS	YES	group 页面段落可折叠

4.2 禁止操作

• 永远不要执行 doxygen -u ：会将精简 Doxyfile 展开为完整配置
• 永远不要用 PowerShell Set-Content/Out-File 修改源文件 ：会破坏 UTF-8 编码，只能用 Edit 工具

4.3 导航树层级规则

• 主页（mainpage.md）的 @subpage → 在导航树中建立一级父子层级
• 普通页面的 @subpage → 只在页面内生成链接，不嵌套到导航树
• @defgroup + @ingroup → "专题"层级在导航树中正确多级嵌套，与页面层级独立

4.4 加粗（ **bold** ）与中文标点

doxygen 的 markdown 解析中， ** 加粗标记的 前后都必须是 ASCII 空格 （或行首/行尾/表格单元格边界），不能紧跟中文字符或中文全角标点（如 ： 、 ， 、 。 、 （ 、 ） ）。否则 ** 不被识别为加粗标记，字面输出 **文字** 。

此外，未识别的 ** 会干扰后续 markdown 解析（包括水平线 --- 、列表等），产生连锁错误——一处加粗写错可能导致后续所有 --- 都不渲染。

正确写法（ ** 前后加 ASCII 空格）：

✅ 句子中： 文字 **加粗文字** 文字
✅ 列表项： - **加粗文字** 后面是空格
✅ 表格中： | **加粗文字** | 说明 |

错误写法（ ** 紧跟中文标点/中文字符）：

❌ 句子中： 文字**加粗文字**文字
❌ 列表项： - **加粗文字**：后面是全角冒号
❌ 冒号后： 解决：**加粗文字**。

行内代码同样受此规则影响 ：反引号标记两侧也需要 ASCII 空格，否则紧跟中文标点时反引号不被识别，字面输出。

❌ 文件（`.vscode`、`.build`）      ← 反引号不被识别
✅ 文件（ `.vscode` 、 `.build` ）   ← 反引号前后加 ASCII 空格

统一规律 ：doxygen 的所有行内标记（加粗、行内代码、斜体等）两侧都需要 ASCII 空格，不能紧跟中文字符或中文全角标点。围栏代码块和缩进代码块内的内容不受此限制。

4.5 正文中的 doxygen 命令必须转义

doxygen 在 markdown 文档中仍然会解析 @ 和 \ 开头的命令。正文中提及 doxygen 命令名时，必须转义，否则 doxygen 会将其识别为命令并执行。

反引号不能保护 @ 命令 ：行内代码中的 @ 命令仍会被 doxygen 识别，反引号会被剥离。必须去掉反引号，用转义格式。

错误：`@page`        ← 反引号被剥离，@page 被识别为命令
正确：\@page          ← 转义后输出字面 @page
 
错误：`\includedoc`   ← 反引号被剥离
正确：\\includedoc     ← 转义后输出字面 \includedoc

块级命令特别危险 ： @code / @endcode / @verbatim / @endverbatim 是"块级"命令，doxygen 识别后会等待对应的 end 命令， 吞掉后续所有 markdown 内容 ，导致标题变 <p> 、水平线 --- 不渲染、表格不渲染等连锁崩溃。

安全区域 （不需要转义）：

• 缩进代码块（4 空格缩进）内

排查方法 ：当 markdown 文档出现结构异常（标题不渲染、 --- 不变水平线、表格变成纯文本段落）， 优先检查正文中是否有未转义的 @ 命令 。可用 doxygen -d markdown 查看解析过程。

---

五、新增组件文档流程

以新增 xt_socket（跨平台 Socket） 文档为例：

1. 创建文档文件 ：components/xt_socket/README.md
2. 声明页面标签 （第一行）：

   # xt_socket 跨平台 Socket {#xt_socket__doc}

3. 在父索引页添加引用 ：编辑 components/README.md，在表格中加一行：

   | @subpage xt_socket__doc ([xt_socket](./xt_socket/README.md)) | 跨平台 Socket |

4. 构建验证 ：

   cd docs
   doxygen Doxyfile

   确认无新增 warning，页面正常生成。

---

六、组件 .md 内容模板

模块文档（__doc）推荐以下章节结构。根据模块特点可增减，但核心章节（概述、API 参考、常见模式、反模式）建议保留。

# {组件名} - {中文名} {#组件名__doc}
 
> 版本：x.x | 日期：yyyy-mm-dd | 路径：`components/...`
 
---
 
## 一、概述
 
（是什么、解决什么问题、一句话设计理念）
 
### 1.1 设计原则
### 1.2 依赖
 
## 二、核心概念
 
（关键概念解释，面向用户理解"为什么这样设计"）
 
## 三、API 参考
 
> 以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 @ref 组件名 。
 
### 3.1 分组名
 
| 函数签名 | 说明 |
|---------|------|
| `返回类型 函数名(参数列表)` | 简短说明 |
 
## 四、编译配置
 
（宏定义表格）
 
## 五、常见模式
 
（使用模式代码示例）
 
## 六、反模式
 
| 反模式 | 问题 | 正确做法 |
|--------|------|----------|
| ... | ... | ... |
 
## 七、测试
 
（测试命令）

6.1 内容原则

• API 参考列函数签名大纲 ：按功能分组列出函数签名表格，完整的参数说明、返回值用 @ref 跳转到 doxygen
• 使用示例和关键场景保留 ：完整使用场景代码（从初始化到清理的完整流程）、特定场景行为说明是 T3 核心价值，不属于 API 细节
• 聚焦 why 和 how ：设计理念、使用模式、反模式是 markdown 文档的核心价值（doxygen 自动生成做不到的）