SuperAPI AI 工具集

write-roxygen-docs

编程与开发

查看项目

更新于 10-16 03:42

技能介绍

用途:为 R 包中的导出函数、内部辅助函数、数据集以及 S3/S4/R6 类编写 roxygen2 文档,并修复文档相关的 R CMD check 提示。

主要能力:在函数上方写 roxygen 注释块,包含标题、描述、@param(每个参数)、@return、@examples、@export、@family、@seealso、@keywords internal 等标签;用 R/data.R 记录数据集,含 @format 的 \describe{} 结构与 @source;用 R/<包名>-package.R 和 "_PACKAGE" 哨兵记录包本身;处理 S3 方法(@rdname 分组)、@inheritParams 复用参数文档、@importFrom rlang .data 修复“no visible binding”警告。

使用方式:按需在 R 文件中书写 #' 注释,然后运行 devtools::document() 生成 man/ 下的 .Rd 文件并重新生成 NAMESPACE;可用 devtools::run_examples() 验证示例,用 devtools::check() 检查文档警告。示例中提供了 weighted_mean 的完整注释写法,涉及 @param x、@param w、@param na.rm、@return、@examples、@export、@family、@seealso 等标签。

适用场景:新增导出函数、内部函数、数据集、类与方法的文档,以及处理 CRAN 对文档的要求。

限制与注意:导出的函数缺失 @return 会触发 CRAN 要求;需要联网或认证的示例应放入 \dontrun{} 并注明原因,耗时示例用 \donttest{};文档由生成而非手写,忘记运行 devtools::document() 会导致页面未更新;roxygen markdown 需在 DESCRIPTION 中设置 Roxygen: list(markdown = TRUE)。相关技能包括 create-r-package、write-testthat-tests、write-vignette、submit-to-cran。