数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载cuDF 是 NVIDIA 开源的 GPU 加速 DataFrame 库其 C 核心引擎 libcudf 的公开 API 文档全部由源码中的 Doxygen 注释自动生成。本文以 cuDF 仓库中 libcudf 的官方文档指南cpp/doxygen/developer_guide/DOCUMENTATION.md对应 Sphinx 入口 docs/cudf/source/libcudf/developer_guide/DOCUMENTATION.rst为主体结合仓库内真实的 Doxyfile、分组定义头文件 doxygen_groups.h 与若干公开头文件源码系统讲解如何为 libcudf 的 C/CUDA 源码书写规范的 Doxygen 块注释、如何使用分组Group/Module组织 API、如何配置并构建 HTML 文档以及 CI 中如何校验文档告警。读完本文你将能直接为 cuDF 仓库新增或修改 API 时写出风格统一、可被 Doxygen 正确渲染并被搜索引擎与文档工具索引的注释。一、为什么需要一套统一的文档指南libcudf 是一个体量庞大且类型体系复杂的 C 库它的公开头文件数量以百计类型包括数值、时间戳、时长、定点数、字符串、字典、列表、结构体等几乎所有算法都要面向这些类型做分派。当 API 数量与注释风格失控时文档的可读性、可检索性与可维护性都会急剧恶化。因此 libcudf 对所有 C 源文件统一采用 Doxygen 风格的注释格式但只有公开 API 与公开类会被真正发布到 API 文档页面。这意味着公开头文件cpp/include/cudf/*.hpp中的每个对外符号都应写完整注释内部实现detail命名空间、src目录、测试代码的注释可以更自由但仍要遵循同一套书写习惯方便源码阅读与代码审查。该指南适用于仓库内所有.hpp、.cpp、.cu、.cuh等 C 相关文件。二、版权许可头每个文件的门面每个 C 源文件的开头都应包含如下许可证头注释/* * SPDX-FileCopyrightText: Copyright (c) 2021-2022, NVIDIA CORPORATION. * SPDX-License-Identifier: Apache-2.0 */两个关键细节注释必须以/*开头而不是/**。因为/**会被 Doxygen 当作文档块处理而许可证头不应该出现在生成的文档中。版权年份规则新建文件写创建年份例如2026修改过的文件应写成区间例如2019-2026创建年-修改年如果只是纯格式调整reformatting而没有内容变化可以不更新年份。在仓库中几乎所有源文件都遵守这一约定例如 cpp/include/cudf/filling.hpp 写的是Copyright (c) 2019-2026而分组定义文件 cpp/include/doxygen_groups.h 写的是Copyright (c) 2021-2026——年份区间如实反映了文件的生命周期。三、Doxygen 工具与 Doxyfile 关键配置Doxygen 是一个从 C 注释生成 HTML 文档的工具它识别块注释中的**近 200 个命令tag**并做专门的排版输出。libcudf 的文档生成行为全部由 cpp/doxygen/Doxyfile当前版本 1.18.0控制。以下是该 Doxyfile 中对 libcudf 定制过的核心选项选项取值作用PROJECT_NAMElibcudf主页面标题PROJECT_NUMBER$(RAPIDS_VERSION)版本号由构建期注入读取仓库根目录 VERSIONEXTENSION_MAPPINGcuC cuhC让 Doxygen 把.cu与.cuhCUDA 源文件/头文件按 C 解析INPUTmain_page.md regex.md unicode.md developer_guide/*.md ../include ...内嵌 Markdown 文件与要处理的源码目录FILE_PATTERNS*.cpp *.hpp *.h *.c *.cu *.cuh参与处理的文件扩展名RECURSIVEYES递归扫描cpp/include下的所有子目录EXCLUDE_PATTERNS*/nvtx/* */detail/* */cudf_test/*排除 NVTX、detail内部实现与测试辅助头文件确保只发布公开 APIEXCLUDE_SYMBOLSorg::apache *_impl *Impl排除第三方符号与实现细节WARN_NO_PARAMDOCYES对缺少参数/返回值文档发出告警帮助作者补全注释MARKDOWN_SUPPORTYES支持注释块中的 Markdown链接、表格、列表等LAYOUT_FILEDoxygenLayout.xml使用 cpp/doxygen/DoxygenLayout.xml 自定义页面布局其中INPUT不仅包含cpp/include源码目录还包含了 5 个开发者指南 Markdown 文件BENCHMARKING.md、DOCUMENTATION.md、DEVELOPER_GUIDE.md、PROFILING.md、TESTING.md以及cudf_test的部分辅助头文件如 column_wrapper.hpp、column_utilities.hpp 等使测试工具类也有文档。四、块注释Block Comments书写规范描述函数、类、其他类型、分组与文件时统一使用下面的块注释风格/** * description text and * doxygen tags go here */要点Doxygen 块以/**开始、以*/结束首尾两行除这两个标记外不能有任何其他字符不要加-----或*****装饰线块必须紧贴在其所描述的源码行之前可以适当缩进以与代码垂直对齐/**与*/之间的每一行都应空格 星号开头正文包括 tag 声明在星号后空一格再写。对比许可证头用/*文档块用/**逻辑注释//绝不用于代码逻辑说明——Doxygen 风格注释只服务于 API 文档。五、标签命名与 Markdown所有 Doxygen 命令统一用前缀如brief、code不使用反斜杠形式注释块内支持 Markdown 的子集链接、表格、列表等均可使用尽量避免直接写 HTML 标签。Doxygen 的 Markdown 对 HTML 的支持有限混合使用容易在生成的网页中出现渲染问题需要注意%与管道符|在 Markdown 表格内的可读性限制必要时调整措辞。六、完整示例文件、类、函数、枚举怎么写指南给出了一份覆盖绝大多数场景的示例浓缩了 libcudf 文档风格的全部要点/** * 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 };从该示例可以提炼出 libcudf 的文档风格骨架简单成员getter/setter、枚举值用行尾///三斜杠注释即可复杂成员与自由函数用完整块注释正文按brief → 详细描述 → 示例代码 → throw/tparam/param/return的顺序组织枚举、模板、命名空间等所有声明类型都能用同一套结构描述。七、描述Descriptions的撰写规范注释中的描述文字应清楚说明输出如何从输入产生并涵盖性能与边界boundary注意事项参数值的取值范围与默认值空值null如何被处理或产生尽量附带一个简短的内联示例。7.1brief一句话简介brief的文本应是一句简短的描述因为 Doxygen 在页面中给它的展示空间很有限brief行之后必须紧跟一个空注释行通常brief相当于标题而非完整句子因此不需要句号只有确实是句子时才加句号。/** * brief Short description or title * * Long description. * */7.2copydoc避免重复文档头文件中的声明应文档完整。当函数定义与声明文档相同、或某个detail函数仅比公开函数多一个stream参数时用copydoc复用文档避免拷贝粘贴导致的双份维护/** * copydoc complicated_function(int,double*,float*) * * Any extra documentation. */对带stream的detail版本/** * 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());注意copydoc必须写完整的函数签名含可选参数Doxygen 才能正确定位到被复制的声明。7.3 参数相关标签的固定顺序函数注释块中以下几组标签应按如下顺序出现在注释块尾部命令说明throw说明函数在何种条件下抛出异常tparam每个模板参数的说明param每个函数参数的说明return对返回对象/值的简短说明throw为函数可能抛出的每一个异常各写一行throw。只需覆盖函数自身抛出的异常如果函数调用的其他函数会抛异常不需要在这里重复记录。异常名不要加反引号以便 Doxygen 正确生成引用链接* throw cudf::logic_error if input_argument is negative or zero说明写throws也合法但 VS Code 等编辑器只对throw做语法高亮因此仓库统一用单数形式throw。tparam为函数声明的每个模板参数写一行tparam参数名必须与模板参数名完全一致描述应说明该参数的要求例如 functor 的输入类型与输出* tparam functor_type The type of the functor * tparam input_type The datatype of the input argumentparam为函数的每个参数写一行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建议把三列文本param[in]、参数名、描述垂直对齐便于在源码编辑器中阅读。描述通常像标题一样简练是句子时才需要句号。return若函数返回对象或值在注释块末尾写一行return简要描述返回内容不要包含返回类型/** * ... * * return A new column of type INT32 and no nulls */7.4 内联示例Inline Examples用code/endcode成对包裹代码示例。Doxygen 默认按所在源文件语言做语法高亮也支持指定语言如.py* code * auto result cudf::make_column( ); * endcode* code{.py} * import cudf * s cudf.Series([1,2,3]) * endcode伪代码示例code{.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 中不如code醒目不要在声明注释中使用example标签——否则 Doxygen 会把整个源文件当作示例源码并把文件单独发布到输出的Examples页面。7.5 弃用标记Deprecations对将在未来版本移除的 API加一行deprecated并在注释中说明替代 API/** * ... * * deprecated This function is deprecated. Use another new function instead. */这与仓库的 API 淘汰策略一致libcudf 演进较快会在可能的情况下用deprecated属性 Doxygendeprecated双重标记并建议替代方案引入弃用的 PR 应打上 deprecation 标签破坏性变更的 PR 打 breaking 标签。八、命名空间Namespaces文档Doxygen 输出包含一个Namespaces页面展示所有带注释块的命名空间。示例/** * brief cuDF interfaces * * This is the top-level namespace which contains all cuDF functions and types. */ namespace CUDF_EXPORT cudf {规则每个唯一的命名空间声明只写一次描述注释。如果出现多处描述Doxygen 会以任意顺序聚合显示造成混乱引入新命名空间时只给其中一个声明写描述块。九、分组与模块Groups/Modules组织 API 的核心机制把声明分组成模块能帮助用户在 Doxygen 页面中快速找到 API。虽然功能相近的函数通常已经按头文件逻辑组织但 Doxygen不会自动按这种方式分组需要显式声明。分组命令可以跨头文件、源文件甚至命名空间聚合公共函数且组内可以嵌套子组。libcudf 的全部分组层次都定义在 cpp/include/doxygen_groups.h 这一个头文件中该文件不需要被任何源文件 include它只被 Doxygen 工具消费用于生成Modules页面只应通过修改该文件来新增或更新分组现有分组经过精心设计与命名新增分组时要谨慎、保持风格一致。从 doxygen_groups.h 可以看到顶层结构的实际形态例如/** * defgroup default_stream Default Stream * defgroup memory_resource Memory Resource Management * defgroup cudf_classes Classes * { * defgroup column_classes Column * { * defgroup column_factories Factories * defgroup column_stream Column stream * defgroup strings_classes Strings * defgroup dictionary_classes Dictionary * defgroup timestamp_classes Timestamp * defgroup lists_classes Lists * defgroup structs_classes Structs * } * defgroup table_classes Table * defgroup scalar_classes Scalar * { * defgroup scalar_factories Factories * } * defgroup fixed_point_classes Fixed Point * } */往下还能看到column_apisColumn and Table、datetime_apisDateTime、strings_apisStrings、dictionary_apis、io_apis、json_apis、lists_apis、labeling_apis、nvtext_apis等一组并列的顶层分组以及它们各自的子组如copy_gather、transformation_fill、aggregation_groupby等这些分组 ID 与 docs/cudf/source/libcudf/api_docs 下的*.rst页面一一对应。9.1 新 API 如何加入分组创建新 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{ ... }成对结构把文件内后续的注释块自动纳入分组省去逐个写ingroup的麻烦namespace CUDF_EXPORT cudf { /** * addtogroup transformation_fill * { */ /** * brief ... * * param ... * return ... */ std::unique_ptrcolumn fill(table_view const input,...); /** } */ } // namespace cudf几个关键细节addtogroup命令块之后必须保留一个空行让 Doxygen 知道它不作用于后面的源码如果addtogroup{ ... }对中包含命名空间声明Doxygen 不会把组应用到其内部条目所以应像上面示例那样把这一对结构放在命名空间花括号之内分组标签职责总结标签/命令使用位置defgroup仅用于 doxygen_groups.h需包含组的标题ingroup头文件中各声明语句的 Doxygen 注释块内addtogroup同一文件内、命名空间内有多个声明时替代ingroup不要指定组标题{ ... }只与addtogroup搭配使用9.2 仓库实例从源码看规范落地在 cpp/include/cudf/copying.hpp 中可以看到上述规范的真实落地。该文件先通过addtogroup column_copy { ... }把整组复制类 API 纳入分组随后每个声明都有完整的brief、ingroup、param、throw、return注释。例如gather的声明/** * brief Gathers the specified rows (including null values) of a set of columns. * * ingroup copy_gather * * Gathers the rows of the source columns according to gather_map such that row i * in the resulting tables columns will contain row gather_map[i] from the source columns. * The number of rows in the result table will be equal to the number of elements in * gather_map. * * A negative value i in the gather_map is interpreted as in, where * n is the number of rows in the source_table. * * throws std::invalid_argument if gather_map contains null values. * * param source_table The input columns whose rows will be gathered * param gather_map View into a non-nullable column of integral indices that maps the * rows in the source columns to rows in the destination columns. * param bounds_policy Policy to apply to account for possible out-of-bounds indices * DONT_CHECK skips all bounds checking for gather map values. NULLIFY coerces rows that * corresponds to out-of-bounds indices in the gather map to be null elements. ... * param stream CUDA stream used for device memory operations and kernel launches * param mr Memory resources used for temporary allocations and the returned table * return Result of the gather */ std::unique_ptrtable gather(table_view const source_table, column_view const gather_map, out_of_bounds_policy bounds_policy out_of_bounds_policy::DONT_CHECK, cuda::stream_ref stream cudf::get_default_stream(), cudf::memory_resources mr cudf::get_current_device_resource_ref());同样cpp/include/cudf/filling.hpp 展示了addtogroup transformation_fill的用法以及throw对异常条件的逐条记录类型不匹配、非法范围、内存重分配需求等——这正是描述应覆盖边界与异常原则的直接体现。文档中的参数类型column_view const、cuda::stream_ref、cudf::memory_resources也印证了开发者指南中规定的输入输出风格输入用视图、流与内存资源作为尾部参数、输出用std::unique_ptr。十、构建 Doxygen 输出10.1 安装 Doxygen推荐两种安装方式conda install doxygen # 或 sudo apt install doxygen也可以从源码自行构建安装。注意仓库 CI 期望的 Doxygen 版本为1.18.0见下文 CI 校验部分。10.2 生成 HTML 文档在包含Doxyfile的 cpp/doxygen 目录下直接运行cd cpp/doxygen doxygen也可以通过 CMake 构建目标生成从 CMake 构建目录例如cpp/buildcmake --build . --target docs_cudf构建过程会读取并处理 cpp/include 目录下所有符合条件的源文件输出到cpp/doxygen/html/目录直接用浏览器打开其中的index.html即可查看本地结果。10.3 在远程服务器上查看文档如果文档构建在远程服务器上可以用 Python 起一个简易 HTTP 服务cd html python -m http.server然后在本地浏览器访问IP地址:8000把 IP 换成运行 HTTP 服务的机器地址。10.4 输出范围说明Doxygen 输出只面向公开 API 与公开类detail目录与src下的实现文件通过EXCLUDE_PATTERNS被排除不会进入发布文档。当构建/CI 系统发布时生成的文档会成为 cuDF 官方文档中 libcudf 部分的内容本仓库内对应 Sphinx 入口见 docs/cudf/source/libcudf/index.rst 与 api_docs 目录。十一、CI 中的文档校验仓库的 CI 脚本 ci/checks/doxygen.sh 专门用于校验 Doxygen 告警其逻辑值得每位贡献者了解版本检查若系统中未安装 doxygen 则跳过打印 warning 并正常退出 0若版本不是 1.18.0打印 Unsupported doxygen version 并跳过版本号注入从仓库根目录 VERSION 文件解析出RAPIDS_VERSION与RAPIDS_VERSION_MAJOR_MINOR并导出供 Doxyfile 中的$(RAPIDS_VERSION)使用告警捕获在cpp/doxygen目录下以cat Doxyfile ; echo QUIET YES; echo GENERATE_HTML NO的方式把配置与覆盖项管道给doxygen -从标准输入读取配置从而只做解析、不生成 HTML快速暴露注释中的问题同时过滤掉缺失 tag 文件类的已知噪音错误结果判定若 doxygen 返回非零或 stderr 非空则以退出码 1 使 CI 失败。这意味着任何新增或修改的注释只要出现文档错误如参数名不匹配、缺少参数文档都会在 CI 中被拦截。因此写注释时务必保证param/tparam名称与声明完全一致并覆盖全部参数与返回值。十二、撰写 libcudf 注释的快速自查清单结合全文为新增或修改 API 补充注释时可按以下清单逐项核对许可证头用/*而非/**年份区间正确文档块用/** ... */紧贴声明之前行内格式为空格星号空格brief一句话简介后跟空行详细描述覆盖输入输出关系、null 处理、边界与性能标签顺序throw→tparam→param→return参数名与签名完全一致必要时标注[in]/[out]/[in,out]模板参数、枚举值、getter/setter 用///行尾注释复杂成员用完整块注释需要分组时新 API 用ingroup 组ID或文件内用addtogroup{ ... }放在命名空间花括号内避免重复文档用copydoc复用含完整签名弃用 API 用deprecated并注明替代方案示例代码用code/endcode类名写完全限定形式提交前确认本机 Doxygen 为 1.18.0并运行 ci/checks/doxygen.sh 风格的校验确保无文档告警。遵循这套规范写出的注释既能让源码在编辑器里整洁易读又能被 Doxygen 稳定地转换成结构清晰、可检索、可引用的 API 文档——这正是 libcudf 这样一个类型繁多、API 庞大的 GPU 计算库保持文档高质量的关键工程实践。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐算法文档编写规范Algorithms39专业注释与API文档标准指南算法文档编写规范Algorithms39专业注释与API文档标准指南 在算法开发中规范的文档编写是确保代码可维护性和团队协作效率的关键。Algorithms示例工程OpenCV项目文档编写指南Doxygen文档生成与编写规范OpenCV项目文档编写指南Doxygen文档生成与编写规范 概述 在OpenCV项目中文档是帮助开发者理解和使用库功能的重要资源。本文将详细介绍如何使用D计算机视觉图像处理深度学习机器学习Rerun C SDK 文档写作指南Doxygen 注释规范、本地构建与版本化发布工作流Rerun C SDK 文档写作指南Doxygen 注释规范、本地构建与版本化发布工作流 Rerun C SDK 的 API 文档由 Doxygen数据可视化3D渲染数据分析上一篇终极vscode-icons指南如何让Visual Studio Code文件管理更直观高效下一篇3Blue1Brown动画仓库实战用3条方程生成洛伦兹吸引子混沌可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考