Matter（Project CHIP）文档风格指南：目录组织、Markdown 规范与 Doxygen 注释实践
【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip
导读：本文以仓库
docs/style/目录下的文档风格指南（style_guide.md）为核心骨架，系统讲解 Matter 项目的文档组织原则、Markdown 书写规范、命令示例约定以及配套的 C++/Python 编码与 Doxygen 注释实践。读完本文，你将掌握向 connectedhomeip 仓库提交文档与代码贡献时应遵循的具体格式要求，并能在实际写文档时参照仓库内真实示例（如 docs/guides 下的各篇指南）做到风格统一、可被搜索引擎与工具链稳定解析。
文档存放位置：docs 目录的组织约定
所有文档贡献都应放置在仓库根目录下docs目录的相应子目录中。文档指南给出了当前（编写时）的目录结构，结合当前仓库实际布局可以对照如下：
| 目录 | 用途 |
|---|---|
docs/guides | 概念性或使用类内容，以及不适合放入子目录的高层教程 |
docs/guides/images | 指南内容中使用的所有图片 |
docs/guides/profiles | 描述或说明 Matter profile 使用的内容 |
docs/guides/test | 与 Matter 测试相关的内容 |
docs/guides/tools | 描述或说明 Matter 工具使用的内容 |
docs/guides/primer | Matter Primer 内容 |
docs/presentations | Matter 特性的 PDF 演示文稿 |
docs/specs | Matter 规范的 PDF 文件 |
images | 顶层 Matter 图片，如 logo |
注意：文档指南中描述的某些子目录（如
docs/guides/profiles、docs/guides/test、docs/presentations、docs/specs）在当前仓库快照中已不存在或尚未创建——它们反映的是指南撰写时的规划，仓库结构本身是持续演进的。实际编写时应遵循“内容优先、就近放置”原则：大多数内容应放入docs/guides及其现有子目录。
当前仓库中docs/guides实际包含的示例包括 BUILDING.md（构建指南）、access-control-guide.md（访问控制指南）、writing_clusters.md（集群编写指南）等，图片统一放在 docs/guides/images 下。如果不确定内容的最佳位置，文档建议创建 Issue 询问，或在 Pull Request 中注明，让维护者协助定夺。
文档风格与链接规范
链接一致性
为保持一致性，所有文档链接都应指向 GitHub 上的内容，且链接文字应具有描述性，让读者一看就知道链接指向什么。在仓库本地撰写时，则使用相对路径，例如 docs/guides/index.md 中就使用[Building](https://link.gitcode.com/i/ade42e17357f31d323f0d1646e95dfae)、[Access Control](https://link.gitcode.com/i/0b07bab3f7a42e26f26af024fcc0704f)这样的描述性链接文字。
Markdown 基础约定
编写 Matter 文档时应使用标准 Markdown。虽然复杂内容（如表格）可以使用 HTML，但应尽可能使用 Markdown。style_guide.md原文档还提示“编辑该文件可查看示例背后的 Markdown 源码”，说明示例本身就是最好的学习材料。
标题层级规范：h1 标题大小写、h2 及以下句子式标题
标题规范是文档可读性和可检索性的基础：
- 文档标题应为
h1（#），采用Title Case（每个单词首字母大写）； - 所有小节标题应为
h2（##）或更低层级，采用sentence case（仅首单词和专有名词首字母大写）。
最佳实践是标题层级不超过 h3，偶尔允许 h4。应避免频繁使用 h4 或更低层级；如果出现这种情况，说明文档需要重新组织或拆分，以保证稳定在 h3（偶尔 h4）的层级结构。
仓库中可以找到大量符合该约定的示例：
- 文档标题（h1，Title Case）：如 BUILDING.md 的
# Building Matter、access-control-guide.md 的# Access Control Guide、batch-commands.md 的# Accepting Batch Commands； - 小节标题（h2，sentence case）：如 BUILDING.md 中的
## Tested Operating Systems、## Build system features、## Checking out the Matter code、## Installing ZAP tool、## Prepare for building、## Build for the host OS (Linux or macOS)。
从源码结构看，这套“h1 标题 Title Case、h2+ 句子式”的约定已被 docs 下绝大多数文档一致执行，是长期稳定有效的仓库惯例。
命令行示例与终端提示符规范
命令前缀：$或%
命令示例可以使用$或%作为前缀，但在同一篇文档或同一组文档中必须保持一致：
$ git clone https://github.com/project-chip/connectedhomeip.git % git clone https://github.com/project-chip/connectedhomeip.git仓库中 docs/guides/BUILDING.md 等指南大量使用$前缀的命令示例，可作为一致性参照。
完整终端提示符格式
如果需要使用包含用户名和主机名的完整终端提示符，采用root@{hostname}{special-characters}#的格式。例如在 Docker 容器中，提示符可能是：
root@c0f3912a74ff:/#代码块与缩进规则
- 所有示例命令和输出都应放在反引号代码块中；
- 但如果代码出现在步骤列表（step list）中，则需要缩进代码块（即使用 4 空格缩进代替围栏代码块）。
步骤列表中的代码块
当流程中包含代码块时，缩进代码块内容：
第一步：
$ git clone https://github.com/project-chip/connectedhomeip.git $ cd connectedhomeip第二步，做其他事情：
$ ./configure
步骤列表中的代码块注意事项
为了指令清晰，应避免在步骤列表的代码示例之后继续追加步骤命令，而是改写指令使其不再需要这样做。
例如，应避免如下写法：
第三步，现在这样做：
$ ./configure然后你会看到那个东西。
而应改为：
第三步，现在这样做，你会看到那个东西：
$ ./configure
行内代码
使用反引号表示行内代码，包括文件路径、文件名或二进制名，例如inline code。
代码注释规范：CHIP 缩写与支持的关键字
代码注释中应使用大写CHIP（因为它是首字母缩写词）。文档列出并给出如下关键字表（示例中包括alarm）：
| 关键字 | 描述 |
|---|---|
| alarm | Alarm |
配套风格体系：编码风格与 Doxygen 注释实践
docs/style目录下的配套文档将文档风格延伸到了源码层面，撰写文档时同样值得遵守：
编码风格指南（CODING_STYLE_GUIDE.md）
CODING_STYLE_GUIDE.md（Revision 6，2024-10-28）规定了 SDK 的核心编码约定：
- 语言标准：C++ 采用 C++17，Python 采用 3.11；
- When in Rome 原则：对既有代码的扩展或修复应匹配原代码的主导风格，绝不因个人喜好擅自整体改写；
- 禁用注释代码：未使用的代码不得用 C/C++ 注释或
#if 0 ... #endif禁用，应直接删除； - 自动格式化工具：C++/Objective-C 使用 clang-format，Java 使用 google-java-format，Python 使用 pep8、isort、ruff，YAML/JSON/markdown 使用 prettier。所有 Pull Request 在合并前都会运行格式检查；
- C++ 细节：使用
cstdint的定宽类型（如uint8_t）；头文件避免顶层using namespace；不暴露在头文件中的类放入匿名命名空间；单例使用GetInstance()命名并删除拷贝/移动构造；核心 SDK 中避免堆分配和自动扩容容器（建议改用就地分配、池分配器、平台分配器）；优先使用CopySpanToMutableSpan而非memcpy；新代码优先std::optional； - Python 细节：公共 API 使用类型提示（type hints）、包含 docstring，并尽量向 mypy 靠拢。
这些规则在仓库源码中有直接对应：池分配器实现见 src/lib/support/Pool.h，Span 相关实现见 src/lib/support/Span.h，平台定义分配器支持见 src/lib/support/CHIPMem.h；Python 的 isort/ruff/mypy 配置可在根目录 pyproject.toml 中查到（例如[tool.isort]设定了line_length = 132与known_first_party = "matter"，[tool.ruff]设定了line-length = 132、target-version = "py311"）。
Makefile 风格（STYLE_MAKEFILES.md）
STYLE_MAKEFILES.md 的约定非常简短：仅应在严格必要时使用 tab，例如避免用 tab 对齐换行。
Doxygen 最佳实践（DOXYGEN.adoc）
DOXYGEN.adoc 针对代码级文档给出了详细约定：
- 每个 C/C++/Objective-C/Perl/Python/Shell/Java 源文件至少应有标准的 Project CHIP 文件头（Apache 2.0 许可头 +
@file简述/详述），C/C++ 使用/* ... */形式，Python/Perl/shell 使用#注释形式； - 所有非平凡公共函数和方法都应带有 Doxygen 前导注释，用
@param[in]/@param[out]说明参数方向与作用、用@retval说明返回值及范围约束； - Do：使用
@标记风格而非\；使用一致的术语；合理断行与对齐； - Don't：不要在 Doxygen 注释中包含文件名、作者姓名、修改日期（版权头除外）或主观意见；不要遗忘为文件、枚举、常量、类、命名空间、函数和方法写注释。
仓库配套的 Doxygen 构建配置位于 docs/Doxyfile 与 docs/ChipDoxygenLayout.xml，文档构建体系（含docs/Makefile、docs/conf.py）已对上述约定形成支撑。
写作建议与工作流总结
- 先定位再动笔：先按 目录组织约定 确定文档归属目录，概念/使用类内容优先进入
docs/guides； - 标题层级：h1 Title Case，h2/h3 sentence case，避免过度下沉到 h4；
- 命令示例：统一
$或%前缀；完整提示符用root@{hostname}#格式；步骤列表内用缩进代码块，且不要在代码示例后追加步骤命令； - 代码与内联代码：块级代码用反引号围栏（步骤列表内缩进），路径与文件名用行内反引号；
- 注释规范：源码注释中大写
CHIP；参考 docs/style 下的配套规范并配合 CODING_STYLE_GUIDE.md 中的格式化工具链（clang-format / ruff / prettier）完成提交前检查； - 不确定就提问：若不确定内容归属，通过 Issue 或 Pull Request 说明，让维护者协助确认，这是指南明确认可的做法。
遵循上述约定，可以保证贡献的文档与 docs 目录下既有内容在结构与风格上保持一致，既便于读者与搜索引擎解析，也有利于后续自动化工具链（Doxygen、Sphinx 文档构建、格式检查）稳定处理。
【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
