libcudf C++ 文档编写指南：基于 Doxygen 的源码注释规范与文档构建实践

数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载本文是 cuDFGPU DataFrame LibraryC 底层库 libcudf 的开发者文档指南完整梳理了仓库内 cpp/doxygen/developer_guide/DOCUMENTATION.md 所规定的 Doxygen 注释规范、标签用法与文档构建流程并结合仓库中的 Doxyfile、doxygen_groups.h、头文件注释实例与 CI 脚本讲解如何为 libcudf 公开 C API 编写规范、完整、可被自动解析的文档。读完本文你将掌握 libcudf 的注释书写约定版权头、块注释、常用标签、模块分组机制ingroup/addtogroup以及本地构建与 CI 校验 HTML 文档的完整方法。适用范围与总体原则这些规范适用于 libcudf所有 C 源文件的 Doxygen 风格注释但只有公开 API 与公开类会被真正发布到线上 API 文档页。Doxygen 生成的 libcudf 文档是 cuDF 官方文档体系中 libcudf API 参考的组成部分因此注释质量直接决定了下游用户与工具包括搜索引擎、Agent 与 LLM对库接口的理解程度。libcudf 文档化的核心原则只对公开接口投入完整的文档编写精力内部实现detail目录、src目录不在发布范围内Doxyfile 中通过排除规则将其过滤每个公开函数、类、枚举、命名空间的注释都应清晰说明输入到输出的转换逻辑并覆盖性能、边界、参数限制、默认值以及 null 值的处理方式注释是源码的一部分书写时应兼顾编辑器中的可读性与Doxygen 渲染页面中的可读性。版权声明头Copyright License每个 C 源文件开头都应包含如下许可证头注释在 cpp/doxygen/developer_guide/DOCUMENTATION.md 中给出实际源码如 doxygen_groups.h 顶部即按此格式书写/* * SPDX-FileCopyrightText: Copyright (c) 2021-2022, NVIDIA CORPORATION. * SPDX-License-Identifier: Apache-2.0 */要点注释必须以/*开头而非/**否则会被 Doxygen 当作文档块处理版权年份规则新文件写创建年份被修改的文件写成区间形式如2019-2021如果只是格式化等无实质内容变更可不更新年份。Doxygen 工具与 Doxyfile 定制Doxygen 负责从 C 注释中生成 HTML 页面它能识别并解析块注释并在遇到 Doxygen 命令本文档中亦称 tag时进行专门的输出格式化。Doxygen 可识别的命令有近 200 个本文档只给出 libcudf 实际使用与推荐的子集。Doxygen 的处理过程可通过 Doxyfile 中的选项定制该文件位于cpp/doxygen/目录。原文档给出了四个关键选项结合当前仓库中 Doxyfile 的实际内容cpp/doxygen/Doxyfile完整整理如下OptionSetting说明PROJECT_NAMElibcudf主页使用的项目标题Doxyfile 第 35 行PROJECT_NUMBER$(RAPIDS_VERSION)版本号。原文档表格中示例为22.02.00当前 Doxyfile 已改为由构建/CI 注入的RAPIDS_VERSION变量第 41 行与仓库 VERSION 文件对应EXTENSION_MAPPINGcuC cuhC将cu与cuh文件按 C 解析第 322-323 行使 CUDA 源文件也能被正确文档化INPUTmain_page.md regex.md unicode.md developer_guide/BENCHMARKING.md developer_guide/DOCUMENTATION.md developer_guide/DEVELOPER_GUIDE.md developer_guide/PROFILING.md developer_guide/TESTING.md ../include 以及 cudf_test 工具头文件与 ../libcudf_kafka/include内嵌 Markdown 文件与要处理的源码目录第 860-875 行。比原文档表格更完整还包含developer_guide/下的多篇开发者指南与 Kafka 扩展头文件FILE_PATTERNS*.cpp *.hpp *.h *.c *.cu *.cuh需要处理的文件扩展名第 904-909 行RECURSIVEYES递归搜索输入目录第 915 行EXCLUDE_PATTERNS/nvtx//detail//cudf_test/排除 NVTX、内部实现detail与测试工具目录第 940-942 行确保只发布公开 APIEXCLUDE_SYMBOLSorg::apache *_impl *Impl排除特定符号第 953-955 行USE_MDFILE_AS_MAINPAGEmain_page.md将 main_page.md 作为主页内容第 1037 行FILTER_PATTERNS*.md./modify_fences.sh对 Markdown 输入应用 modify_fences.sh 过滤第 1015 行SEARCHENGINEYES生成内置搜索框第 1650 行INPUT中的相对路径是相对于cpp/doxygen目录解析的因此../include实际指向仓库的cpp/include。块注释Block Comments书写风格描述函数、类、其他类型、分组与文件的块注释统一采用如下风格/** * description text and * doxygen tags go here */规则细节Doxygen 注释块以/**开始、以*/结束且首尾行不允许再有其他内容——不要在首尾行添加横线-----或星号*****块必须紧邻其所描述的源码行之前块可以按需缩进以便与所描述条目在垂直方向上对齐/**与*/之间的每一行应以「一个空格 一个星号」开头星号之后的所有文本包括标签声明再空一格书写。标签/命令命名约定统一使用作为 Doxygen 命令前缀例如brief、code等而不是反斜杠\形式。Markdown 支持与限制Doxygen 的 Markdown 支持是受限的注释块内可以使用链接、表格、列表等格式。在源码文本可读性与 Doxygen 网页可读性之间有时需要权衡——例如 Markdown 表格中的%字符与管道符|存在可读性限制%在 Doxygen 中另有禁用自动链接的语义见 Doxyfile 的AUTOLINK_SUPPORT相关说明。应避免直接使用 HTML 标签虽然 Doxygen 的 Markdown 支持 HTML 标签但其 HTML 支持同样是受限的混用容易造成渲染异常。完整示例注释块与标签的典型用法以下是 cpp/doxygen/developer_guide/DOCUMENTATION.md 给出的示例几乎覆盖了 libcudf 中 Doxygen 块注释与标签的全部常见形态/** * file source_file.cpp * brief Description of source file contents * * Longer description of the source file contents. */ /** * brief One line description of the class * * ingroup optional_predefined_group_id * * Longer, more detailed description of the class. * * tparam T Short description of each template parameter * tparam U Short description of each template parameter */ template typename T, typename U class example_class { void get_my_int(); /// Simple members can be documented like this void set_my_int( int value ); /// Try to use descriptive member names /** * brief Short, one line description of the member function * * A more detailed description of what this function does and what * its logic does. * * code * example_classint inst; * inst.set_my_int(5); * int output inst.complicated_function(1,dptr,fptr); * endcode * * param[in] first This parameter is an input parameter to the function * param[in,out] second This parameter is used both as an input and output * param[out] third This parameter is an output of the function * * return The result of the complex function */ T complicated_function(int first, double* second, float* third) { // Do not use doxygen-style block comments // for code logic documentation. } private: int my_int; /// An example private member variable }; /** * brief Short, one line description of this free function * * ingroup optional_predefined_group_id * * A detailed description must start after a blank line. * * code * templatetypename T * struct myfunctor { * bool operator()(T input) { return input % 2 0; } * }; * free_functionmyfunctor,int(myfunctor{},12); * endcode * * throw cudf::logic_error if input_argument is negative or zero * * tparam functor_type The type of the functor * tparam input_type The datatype of the input argument * * param[in] functor The functor to be called on the input argument * param[in] input_argument The input argument passed into the functor * return The result of calling the functor on the input argument */ template class functor_type, typename input_type bool free_function(functor_type functor, input_type input_argument) { CUDF_EXPECTS( input_argument 0, input_argument must be positive); return functor(input_argument); } /** * brief Short, one line description * * ingroup optional_predefined_group_id * * Optional, longer description. */ enum class example_enum { first_enum, /// Description of the first enum second_enum, /// Description of the second enum third_enum /// Description of the third enum };示例中值得注意的细节单行成员与枚举值可使用行尾///形式快速注释函数逻辑的注释应使用普通//注释不要用 Doxygen 风格块注释详细描述必须与brief之间留一个空行函数体内的局部注释不属于 API 文档范畴。描述规范Descriptions注释描述应清楚说明输出如何由输入产生并包含性能考量与边界情况说明参数值的限制与是否声明了默认值不要忘记说明 null 值如何处理或产生条件允许时尽量附带一个简短示例。briefbrief文本应是一行简短描述。Doxygen 在输出页面中给 brief 文本的空间很小因此它更像标题而非句子通常不需要句号除非它确实是完整句子。brief行之后必须跟一个空的注释行之后才是长描述即注释块中未被任何 Doxygen 命令标记的其余文本/** * brief Short description or title * * Long description. *copydoc头文件中的声明文档应当清晰完整。为避免函数定义处重复整段注释可使用copydoc标签引用已有注释/** * copydoc complicated_function(int,double*,float*) * * Any extra documentation. */copydoc在文档化仅因stream参数不同而不同的detail函数时特别有用——公开函数与 detail 版本共享文档只追加说明 stream 参数/** * copydoc cudf::segmented_count_set_bits(bitmask_type const*,std::vectorsize_type const) * * param[in] stream Optional CUDA stream on which to execute kernels */ std::vectorsize_type segmented_count_set_bits(bitmask_type const* bitmask, std::vectorsize_type const indices, cuda::stream_ref stream cudf::get_default_stream());必须写出函数的完整签名包括可选参数Doxygen 才能正确定位被复制的注释。这一模式在仓库中广泛使用例如 cpp/include/cudf/copying.hpp 中slice/split的 column 与 table 重载即通过copydoc cudf::slice(...)复用注释。函数参数标签的顺序以下标签应出现在函数注释块末尾附近并按下表顺序排列CommandDescriptionthrow说明函数可能抛出异常的条件tparam每个模板参数的说明param每个函数参数的说明return返回对象或值的简短说明throw为函数可能抛出的每一个异常添加一行throw注释。只需包含函数自身抛出的异常如果函数调用了其他可能抛异常的函数不需要在此记录那些异常。异常名不要加反引号以便 Doxygen 正确生成引用链接* * throw cudf::logic_error if input_argument is negative or zero *使用throws亦可但 VS Code 等工具只对throw做语法高亮因此统一推荐throw。仓库中的实际例子可参考 cpp/include/cudf/filling.hppfill的 in-place 版本用多个throws cudf::logic_error分别说明「需要内存重分配」「范围无效begin 0 等」「destination 与 value 类型不同」「value 非法而 destination 非空」等条件。tparam为函数声明的每个模板参数添加一行tparam标签后指定的参数名必须与模板参数名完全一致。定义应说明参数的要求例如若模板是 functor 或 predicate则描述期望的输入类型与输出* * tparam functor_type The type of the functor * tparam input_type The datatype of the input argument *param为传给函数的每个参数添加一行param参数名必须与函数参数名匹配。若参数方向无法从声明与命名中明确看出应追加[in]、[out]或[in,out]* * param[in] first This parameter is an input parameter to the function * param[in,out] second This parameter is used both as an input and output * param[out] third This parameter is an output of the function *建议尽量将三列文本垂直对齐便于在源码编辑器中阅读。描述通常也如标题一般仅当是完整句子时才加句号。return若函数返回对象或值在注释块末尾添加一行return并简要描述返回内容。不要在return注释中包含返回类型类型信息由声明给出/** * ... * * return A new column of type INT32 and no nulls */内联示例Inline Examples在注释块中附带源代码示例通常很有帮助使用code与endcode标签对* * code * auto result cudf::make_column( ); * endcode *Doxygen 支持 C 及多种语言如 Python、Java的语法高亮默认code按所在源码的语言高亮。可通过标签内指定文件扩展名切换语言* * code{.py} * import cudf * s cudf.Series([1,2,3]) * endcode *需要伪代码时可使用{.pseudo}* * Sometimes pseudocode is clearer. * code{.pseudo} * s int column of [ 1, 2, null, 4 ] * r fill( s, [1, 2], 0 ) * r is now [ 1, 0, 0, 4 ] * endcode *编写示例片段时使用全限定类名可让 Doxygen 在示例中生成引用链接* * code * auto result1 make_column( ); // reference link will not be created * auto result2 cudf::make_column( ); // reference link will be created * endcode *虽然三个反引号 的代码块也能工作但在 VS Code 等源码编辑器中不够醒目故不推荐。切勿在声明注释中使用example标签——Doxygen 会把整个源文件当作示例源代码并将其发布到输出中独立的Examples页面。弃用标记Deprecations对将在未来版本移除的 API添加一行deprecated注释并在注释中提及替代/替换 API/** * ... * * deprecated This function is deprecated. Use another new function instead. */命名空间NamespacesDoxygen 输出包含一个Namespaces页面展示所有带注释块的命名空间声明。示例/** * brief cuDF interfaces * * This is the top-level namespace which contains all cuDF functions and types. */ namespace CUDF_EXPORT cudf {规则每个唯一的命名空间声明只写一次描述注释。若同一命名空间出现多处描述Doxygen 会以任意顺序聚合这些描述导致输出混乱。引入新命名空间时只需为一个声明提供描述块。分组与模块Groups/Modules将声明归组到模块中有助于用户在 Doxygen 页面中快速找到 API。虽然公共函数通常已在头文件中按逻辑分组但 Doxygen不会自动按此方式组织输出。Doxygen 输出包含一个Modules页面它使用 Doxygen 的分组命令将条目组织为组。分组命令可以跨头文件、源文件甚至命名空间对公共函数分组组之间还可以嵌套在已有组内定义新组。doxygen_groups.h分组的单一事实来源libcudf 的全部组层级都定义在 cpp/include/doxygen_groups.h 头文件中。该文件不需要被任何源文件包含——其中的定义只被 Doxygen 工具用于生成Modules页面因此修改此文件只应为添加或更新组。既有的组经过了精心结构与命名新增组时应谨慎考量。从仓库中的 doxygen_groups.h 可以看到完整的组树结构顶层包括default_stream、memory_resource、cudf_classesClasses含 Column/Table/Scalar/Fixed Point 等子组、column_apisColumn and Table含 Copying/Sorting/Searching/Hashing/Merging/Joining/Quantiles/Reduction/Aggregation/Transformation/Reshaping/Reordering/Interop 等子组、datetime_apis、strings_apis、dictionary_apis、io_apis、json_apis、lists_apis、nvtext_apis、utility_apis、labeling_apis、expressions与tdigest等。新增 API 时从其对应功能域如字符串、IO、Lists查找并复用已有组 id 即可。使用 ingroup 归组创建新 API 时用ingroup标签并指定 doxygen_groups.h 中的组引用 idnamespace CUDF_EXPORT cudf { /** * brief ... * * ingroup transformation_fill * * param ... * return ... */ std::unique_ptrcolumn fill(table_view const input,...); } // namespace cudf使用 addtogroup 批量归组也可用addtogroup配合{ ... }标签对将文件内的 Doxygen 注释块自动纳入某个组namespace CUDF_EXPORT cudf { /** * addtogroup transformation_fill * { */ /** * brief ... * * param ... * return ... */ std::unique_ptrcolumn fill(table_view const input,...); /** } */ } // namespace cudf这可以省去在文件内每个注释块中单独写ingroup。注意事项addtogroup命令块之后必须保留一个空行让 Doxygen 知道它不作用于后续源码若addtogroup与{ ... }对包含命名空间声明Doxygen 不会将组赋给条目——因此必须像上面的示例那样把addtogroup与{ ... }放在命名空间声明的大括号之间。分组标签速查表Tag/CommandWhere to usedefgroup仅用于 doxygen_groups.h且应包含组的标题ingroup在头文件声明语句的单个 Doxygen 注释块内使用addtogroup对同一文件、同一命名空间内的多个声明使用替代逐个ingroup不要指定组标题{ ... }仅与addtogroup搭配使用构建 Doxygen 输出安装 Doxygen推荐通过 condaconda install doxygen或 Linux 包管理器sudo apt install doxygen安装 Doxygen也可从源码自行构建。注意当前仓库 CI 校验脚本 ci/checks/doxygen.sh 期望的 Doxygen 版本为1.18.0版本不匹配时会直接跳过校验并给出 warning。两种构建方式方式一直接运行 doxygen 命令在包含 Doxyfile 的cpp/doxygen目录中运行cd cpp/doxygen doxygenDoxygen 读取并处理cpp/include/下所有符合条件的源文件输出生成到cpp/doxygen/html/目录Doxyfile 中HTML_OUTPUT html且OUTPUT_DIRECTORY留空表示当前目录。可以直接用浏览器打开本地生成的index.html查看结果。方式二通过 CMake 目标构建在 cmake 构建目录如cpp/build中运行cmake --build . --target docs_cudf仓库 cpp/CMakeLists.txt 中定义了docs_cudf自定义目标它通过add_custom_command在${CUDF_SOURCE_DIR}/doxygen工作目录下执行doxygen Doxyfile并注入RAPIDS_VERSION与RAPIDS_VERSION_MAJOR_MINOR环境变量——这正是 Doxyfile 中PROJECT_NUMBER $(RAPIDS_VERSION)变量值的来源。远程查看文档若文档构建在远程服务器上可用 Python 启动简易 HTTP 服务器cd html python -m http.server然后在本地浏览器中打开http://IP地址:8000将 IP 替换为运行 HTTP 服务器机器的地址。发布范围与 CI 校验Doxygen 输出只面向公开 API 与公开类例如输出不应包含detail或src文件这些目录已在 Doxyfile 的EXCLUDE_PATTERNS*/nvtx/*、*/detail/*、*/cudf_test/*与EXCLUDE_SYMBOLSorg::apache、*_impl、*Impl中排除。构建/CI 系统发布后doxygen 输出会成为 cuDF 官方文档中 libcudf API 参考的一部分。仓库还提供了一键校验脚本 ci/checks/doxygen.sh它会从仓库根目录的 VERSION 文件解析出RAPIDS_VERSION然后以QUIET YES、GENERATE_HTML NO的追加配置运行 doxygen并过滤掉缺失 tag 文件类错误任何剩余 stderr 输出都会导致校验失败——这保证了文档注释在 CI 层面持续保持无告警状态。延伸阅读完整的开发者规范体系见 cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md基准测试、性能分析与测试相关的文档规范见 cpp/doxygen/developer_guide/BENCHMARKING.md、cpp/doxygen/developer_guide/PROFILING.md 与 cpp/doxygen/developer_guide/TESTING.md文档主页内容与正则、Unicode 专题分别见 cpp/doxygen/main_page.md、cpp/doxygen/regex.md 与 cpp/doxygen/unicode.md分组定义的唯一权威文件是 cpp/include/doxygen_groups.h新增 API 时按其中已有组 id 使用ingroup或addtogroup想观察标签在真实代码中的落地形态可参考 cpp/include/cudf/filling.hppbrief/throws/param的密集使用与 cpp/include/cudf/copying.hppcopydoc复用声明文档。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐libcudf C 文档编写指南Doxygen 注释规范与 API 文档构建实践cuDFlibcudf C 文档编写指南Doxygen 注释规范与 API 文档构建实践cuDF cuDF 是 NVIDIA 开源的 GPU 加速 DataF数据分析数据工程机器学习uWebSockets源码注释规范Doxygen与文档生成uWebSockets源码注释规范Doxygen与文档生成 项目概述 uWebSockets是一个简单、安全且符合标准的Web服务器适用于最苛刻的应用场景。后端网络消息路由WebSocketReactiveCocoa 代码注释规范基于 Xcode Markup 的 Swift 文档编写实战指南ReactiveCocoa 代码注释规范基于 Xcode Markup 的 Swift 文档编写实战指南 导读 本文以 ReactiveCocoa 仓库中的UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考