Rerun C++ SDK 文档写作指南：Doxygen 注释规范、本地构建与版本化发布工作流

Rerun C SDK 文档写作指南Doxygen 注释规范、本地构建与版本化发布工作流【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunRerun C SDK 的 API 文档由 Doxygen 为骨架完整讲解 C 文档的注释书写规范、本地构建与预览流程、版本化文档的生成发布机制并结合 Doxyfile 与源码实例给出可落地的实践细节。一、文档工作流总览从源码注释到在线文档Rerun C SDK 的文档体系是一条自动化流水线开发者在头文件中使用///风格的 Doxygen 注释书写 API 文档构建时由 MkDoxy 插件调用 Doxygen 提取注释、解析 Markdown生成 HTML 站点本地产出位于rerun_cpp/docs/html/线上版本则由 CI 发布到版本化域名路径。这一流程决定了文档的第一入口是源码注释本身因此注释质量直接决定 API 文档质量。整条流水线通过 pixi 环境管理构建命令定义在 pixi.toml 中cpp-docs任务cwd为rerun_cppcpp-docs { cmd doxygen docs/Doxyfile echo ***************\nSuccess!\nOpen ./rerun_cpp/docs/html/index.html in your browser., cwd rerun_cpp }可以看到该任务先运行doxygen docs/Doxyfile成功后提示打开rerun_cpp/docs/html/index.html预览。二、本地构建与预览文档2.1 构建命令在仓库根目录执行pixi run -e cpp cpp-docs-e cpp指定 pixi 环境包含 Doxygen 等工具链cpp-docs对应 pixi.toml 中定义的任务。构建完成后用浏览器打开rerun_cpp/docs/html/index.html2.2 Doxygen 配置的关键设定Doxyfile 是本次构建的配置文件几个与文档范围直接相关的选项配置项值作用PROJECT_NAMERerun C SDK生成站点标题出现在每个页面顶部OUTPUT_DIRECTORYdocs输出目录配合cwd rerun_cpp即生成到rerun_cpp/docs/html/OUTPUT_LANGUAGEEnglish生成页面语言INPUTREADME.md、cmake_setup_in_detail.md、arrow_cpp_install.md、src/文档输入源三个 Markdown 手册 全部源码目录FILE_PATTERNS*.md、*.hpp只解析 Markdown 与头文件API 文档以头文件为准RECURSIVEYES递归扫描src/下所有子目录USE_MDFILE_AS_MAINPAGEREADME.md将 rerun_cpp/README.md 作为站点首页GENERATE_HTMLYES生成 HTML 输出WARN_AS_ERRORFAIL_ON_WARNINGS出现文档警告时以非零状态结束构建强制保持文档健康其中WARN_AS_ERROR FAIL_ON_WARNINGS值得特别注意它不中断处理但一旦存在未解析引用、错误命令等警告构建即以失败告终。这意味着注释里的每一个\命令、每一个类型引用都必须正确否则本地构建会直接报错——这是保证文档质量的硬性门槛。2.3 定制化 HTML 外观构建出的站点并非 Doxygen 默认样式而是通过 rerun_cpp/docs/header.html 自定义了 HTML 头部并在 Doxyfile 中配置了HTML_HEADER docs/header.html自定义页头模板HTML_EXTRA_STYLESHEET docs/doxygen-awesome/doxygen-awesome.css接入 Doxygen Awesome 主题HTML_EXTRA_FILES docs/doxygen-awesome/doxygen-awesome-darkmode-toggle.js ...附带暗色模式切换与代码片段复制按钮脚本。从 header.html 可以看到页面加载了doxygen-awesome-darkmode-toggle.js与doxygen-awesome-fragment-copy-button.js分别提供深色模式开关和一键复制代码片段功能。相关资源位于 rerun_cpp/docs/doxygen-awesome/。三、版本化文档的生成与发布机制线上文档与本地构建使用完全相同的流程生成托管在公网对象存储上。发布规则如下每个合并到 main 分支的提交都会生成一份滚动最新文档对应路径为docs/cpp/main每次发版会额外生成一份固化版本文档路径形如docs/cpp/0.23.3以实际发布版本号为准。这种main/ 版本号双轨并行的设计让使用者既可以查阅最新开发版 API也能锁定某个具体 SDK 版本的接口行为避免文档与代码版本错位。由于发布过程由 CI 在每次提交与打标签时自动触发开发者本地只需保证构建成功尤其是WARN_AS_ERROR约束下不产生警告即可让线上文档保持最新。四、C 文档注释书写规范文档由 MkDoxy 插件处理其内部调用 Doxygen 提取注释。Rerun C SDK 统一采用以下注释风格保证全仓库文档的一致性4.1 基础语法规则统一使用///作为文档注释标记不使用/** */或//!Doxygen 命令一律以反斜杠\开头例如\private、\cond、\endcond能用 Markdown 表达的内容优先用 Markdown尽量少用 Doxygen 专用命令提高源码可读性与渲染一致性禁止使用\brief规范要求在注释顶部写一行简短描述空一行后再写详细说明。Doxygen 会将首个段落作为 brief后续段落作为 detailed description。一个符合规范的注释示例取自 rerun_cpp/src/rerun/recording_stream.hpp 的实际风格/// Creates a new recording stream to log to. /// /// All log functions early out if a recording stream is disabled. /// Naturally, logging functions that take unserialized data will skip the serialization step as well. rerun::RecordingStream(std::string_view app_id);4.2 隐藏内部实现\private与\condC 头文件中包含大量内部辅助类型需要从公开 API 文档中隐藏隐藏单个类或方法在注释中直接使用\private隐藏成片条目用条件块包裹/// \cond private ... // 需要隐藏的实现细节 /// \endcond真实用例可在 rerun_cpp/src/rerun/as_components.hpp 中找到AsComponents主模板是公开文档化的 trait而对CollectionComponentBatch、单个ComponentBatch及其Result包装等内置特化实现则被/// \cond private整体隐藏并注明Documenting the builtin genericAsComponentsimpls is too much clutter for the doc class overview为内置泛型实现编写文档会让类总览过于杂乱。同样的模式也出现在 rerun_cpp/src/rerun/collection_adapter_builtins.hpp 中。4.3 组织方式用命名空间而非分组避免使用 Doxygen 分组groups当命名空间可以表达相同层级时应优先使用命名空间引用类型时不要省略命名空间写rerun::Collection而不是Collection。两者通常都能工作但完整的限定名能让读者立刻明确类型所属作用域尤其在文档交叉引用与自动链接AUTOLINK_SUPPORT场景下更准确。4.4 规范速查表场景写法文档注释标记///Doxygen 命令前缀\如\private富文本格式优先 Markdown少用 Doxygen 命令简短描述顶部单行空行后接详细说明不用\brief隐藏单个条目注释内写\private隐藏多个条目/// \cond private…/// \endcond分组避免 groups用命名空间类型引用使用完整限定名如rerun::Collection五、源码中的规范实例解析5.1RecordingStream的文档风格rerun_cpp/src/rerun/recording_stream.hpp 是体现上述规范的最佳样本类级注释以单行摘要开头空行后展开多段详细说明描述内部管线线性化、微批量micro-batching处理、自动时间戳等行为成员函数注释同样遵循单行摘要 空行 细节的结构并用纯文本而非\brief表达 brief 段落。5.2AsComponents的隐藏与公开边界rerun_cpp/src/rerun/as_components.hpp 演示了如何在一个模板 trait 上划分公开文档与内部实现公开部分是AsComponentsT主模板及其as_batches说明以及引导使用者实现自定义特化的static_assert报错信息内部则是一系列/// \cond private//// \endcond包裹的特化避免类总览被模板噪音淹没。这正是用\cond隐藏成片条目规范在真实代码中的应用。六、文档片段与测试的联动除了 Doxygen 注释文档中还嵌入了大量可执行代码片段。仓库专门维护了 rerun_cpp/docs/readme_snippets.cpp其文件头注释明确说明// File used for snippets that are embedded in the documentation. // Compiled as part of the tests to make sure everything keeps working!该文件以/// [Logging]、/// [Streaming]、/// [Connecting]、/// [Buffering]等标签标记代码段边界覆盖了日志记录、保存.rrd文件、gRPC 连接、缓冲后延迟连接等典型使用场景。它作为测试的一部分参与编译确保文档中的示例代码始终可用——写文档的同时也在维护回归测试这是保持文档不腐烂的关键机制。七、为文档新增 Markdown 手册需要补充长篇指南而非 API 注释时只需把.md文件加入 Doxyfile 的INPUT列表并确保符合FILE_PATTERNS *.md与RECURSIVE YES的扫描规则即可。当前输入包括rerun_cpp/README.md作为USE_MDFILE_AS_MAINPAGE指定的首页rerun_cpp/docs/cmake_setup_in_detail.mdCMake 集成细节rerun_cpp/docs/arrow_cpp_install.mdArrow C 安装说明。新增手册后运行pixi run -e cpp cpp-docs即可在本地验证渲染效果由于WARN_AS_ERROR FAIL_ON_WARNINGS任何 Markdown 引用错误或链接失效都会在构建期暴露。八、写作与提交检查清单结合上述全流程为 Rerun C SDK 贡献文档时的完整检查清单如下注释使用///命令前缀用\优先 Markdown顶部单行摘要 空行 详细描述不使用\brief内部实现用\private或\cond private/\endcond隐藏用命名空间组织层级避免 groups类型引用写全限定名如rerun::Collection文档片段如需嵌入同步更新 rerun_cpp/docs/readme_snippets.cpp 并保证其通过编译本地执行pixi run -e cpp cpp-docs验证构建无警告WARN_AS_ERROR会在有警告时令构建失败并检查rerun_cpp/docs/html/index.html的渲染结果合并到 main 后线上docs/cpp/main将自动更新发版后新增版本化文档。这套注释规范 构建工具链 CI 发布 片段测试的组合使 Rerun C SDK 的文档能够与代码同步演进既保证了 API 参考的准确性也确保了示例代码的长期可用性。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考