MatterProject 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/primerMatter Primer 内容docs/presentationsMatter 特性的 PDF 演示文稿docs/specsMatter 规范的 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的层级结构。仓库中可以找到大量符合该约定的示例文档标题h1Title Case如 BUILDING.md 的# Building Matter、access-control-guide.md 的# Access Control Guide、batch-commands.md 的# Accepting Batch Commands小节标题h2sentence 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 容器中提示符可能是rootc0f3912a74ff:/#代码块与缩进规则所有示例命令和输出都应放在反引号代码块中但如果代码出现在步骤列表step list中则需要缩进代码块即使用 4 空格缩进代替围栏代码块。步骤列表中的代码块当流程中包含代码块时缩进代码块内容第一步$ git clone https://github.com/project-chip/connectedhomeip.git $ cd connectedhomeip第二步做其他事情$ ./configure步骤列表中的代码块注意事项为了指令清晰应避免在步骤列表的代码示例之后继续追加步骤命令而是改写指令使其不再需要这样做。例如应避免如下写法第三步现在这样做$ ./configure然后你会看到那个东西。而应改为第三步现在这样做你会看到那个东西$ ./configure行内代码使用反引号表示行内代码包括文件路径、文件名或二进制名例如inline code。代码注释规范CHIP 缩写与支持的关键字代码注释中应使用大写CHIP因为它是首字母缩写词。文档列出并给出如下关键字表示例中包括alarm关键字描述alarmAlarm配套风格体系编码风格与 Doxygen 注释实践docs/style目录下的配套文档将文档风格延伸到了源码层面撰写文档时同样值得遵守编码风格指南CODING_STYLE_GUIDE.mdCODING_STYLE_GUIDE.mdRevision 62024-10-28规定了 SDK 的核心编码约定语言标准C 采用 C17Python 采用 3.11When in Rome 原则对既有代码的扩展或修复应匹配原代码的主导风格绝不因个人喜好擅自整体改写禁用注释代码未使用的代码不得用 C/C 注释或#if 0 ... #endif禁用应直接删除自动格式化工具C/Objective-C 使用 clang-formatJava 使用 google-java-formatPython 使用 pep8、isort、ruffYAML/JSON/markdown 使用 prettier。所有 Pull Request 在合并前都会运行格式检查C 细节使用cstdint的定宽类型如uint8_t头文件避免顶层using namespace不暴露在头文件中的类放入匿名命名空间单例使用GetInstance()命名并删除拷贝/移动构造核心 SDK 中避免堆分配和自动扩容容器建议改用就地分配、池分配器、平台分配器优先使用CopySpanToMutableSpan而非memcpy新代码优先std::optionalPython 细节公共 API 使用类型提示type hints、包含 docstring并尽量向 mypy 靠拢。这些规则在仓库源码中有直接对应池分配器实现见 src/lib/support/Pool.hSpan 相关实现见 src/lib/support/Span.h平台定义分配器支持见 src/lib/support/CHIPMem.hPython 的 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.mdSTYLE_MAKEFILES.md 的约定非常简短仅应在严格必要时使用 tab例如避免用 tab 对齐换行。Doxygen 最佳实践DOXYGEN.adocDOXYGEN.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使用标记风格而非\使用一致的术语合理断行与对齐Dont不要在 Doxygen 注释中包含文件名、作者姓名、修改日期版权头除外或主观意见不要遗忘为文件、枚举、常量、类、命名空间、函数和方法写注释。仓库配套的 Doxygen 构建配置位于 docs/Doxyfile 与 docs/ChipDoxygenLayout.xml文档构建体系含docs/Makefile、docs/conf.py已对上述约定形成支撑。写作建议与工作流总结先定位再动笔先按 目录组织约定 确定文档归属目录概念/使用类内容优先进入docs/guides标题层级h1 Title Caseh2/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），仅供参考