文档编写规范

本文档规定项目文档编写的格式和语法规范，适用于 Markdown 文档、PlantUML 图表以及源码注释中的中文文本。

---

中英文间距

参考 Snapmaker 中文写作风格指南 2.3。

基本规则

汉字与西文（英文字母、数字）之间始终保留一个空格；西文与西文之间不加空格。

• 正确：使用 Kotlin 2.3.20 进行开发、第 3 步、MVI 架构
• 错误：使用Kotlin 2.3.20进行开发、第3步、MVI架构

符号视作西文

百分号（%）、连字符（-）、斜杠（/）、加号（+，表非运算时）、冒号（:）、点（.）等符号与汉字之间空一格，与西文之间不空格。

• 正确：设置能量为 30%、输入 - 按键 - 反馈布局
• 错误：设置能量为 30 %、输入-按键-反馈布局

运算符号前后各空一格

加号（+）、减号（−）、乘号（×）、除号（÷）、等于号（=）等运算符号前后无论汉字还是西文均空一格。

• 正确：300mm × 200mm × 200mm

型号与规格视作西文

版本号（V1.3.0）、尺寸（10mm-20mm）、型号（A350、M4×8）等整体视作西文，与汉字之间空一格，内部不加空格。

日期数字视作西文

遵循与汉字（"年""月""日"）之间空一格的规则。

• 正确：2020 年 12 月 24 日

不适用的情况

• 中文字符与标点符号（中文或英文标点）之间不需要加空格
• 代码块内的代码不受此规则约束
• 字符替换占位符（如 %s、%d、{0} 等）与相邻中文之间不加空格
• 表示路径、目录、文件名的文本内部不加空格（如 values/ 文件夹、月-日 命名格式）

适用范围

Markdown 文档、PlantUML 图表中的标签和注释、源码中的注释和中文文本字符串、配置与国际化资源文件中的文本。

---

PlantUML 语法注意事项

混用类图与用例图

同一图表中同时使用 class/package 和 usecase 时，必须在 @startuml 后添加 allowmixing 指令，否则渲染报错。

跨分区注释

note across 只能用于泳道图（|分区|），非泳道图的分区注释应使用 note bottom of <element> 或 note right of <element>。

多行方法体

类成员中的多行方法体不能直接换行书写，需用 \n 转义为单行字符串，如：

dispatchEditorAction(output) : {\n  when(output) {\n    ...\n  }\n}

外部文件导入

在 Markdown 中嵌入 PlantUML 必须使用 plantuml 代码块 + @file: 语法（而非 > @file: 引用块），否则 vitepress-plugin-diagrams 无法识别和渲染。

• 正确：以 ```plantuml 开头的代码块，内含 @file:../diagrams/architecture.puml
• 错误：> @file:../diagrams/architecture.puml（引用块语法不会被插件处理）

PUML 中的 \n 不是英文

\n 是 PlantUML 的换行转义序列，不是英文字母，其与相邻中文之间不加空格。

---

Markdown 语法注意事项

尖括号被识别为 HTML 标签

当 <...> 成对出现时（如泛型 StateFlow<ImeState>），Markdown 解析器会将其视为 HTML 标签并吞没内容。必须用反引号包裹：`StateFlow<ImeState>`

文档交叉引用

• 使用相对路径链接，不要使用「文档 160」「文档 800」等抽象编号
• 文件重命名后必须同步更新所有引用该文件的链接
• 跨目录引用注意相对路径层级（如从 architecture/ 引用 engine/ 的文件需用 ../engine/）