编写 Roxygen 文档
为 R 包函数、数据集和类创建完整的 roxygen2 文档。
适用场景
- 为新导出函数添加文档
- 记录内部辅助函数
- 记录包数据集
- 记录 S3/S4/R6 类及方法
- 修复文档相关的
R CMD check注记
输入
- 必需:需要记录的 R 函数、数据集或类
- 可选:用于交叉引用的相关函数(
@family、@seealso) - 可选:函数是否应导出
步骤
第 1 步:编写函数文档
将 roxygen 注释直接放在函数上方:
#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
# implementation
}
预期结果: 完整的 roxygen 块,包含标题、描述、每个参数的 @param、@return、@examples 以及 @export。
失败处理: 若对某个标签不确定,查阅 ?roxygen2::rd_roclet。常见遗漏是 @return,CRAN 要求所有导出函数必须包含此标签。
第 2 步:基本标签参考
| 标签 | 用途 | 导出时是否必需? |
|---|---|---|
#' Title |
首行,一句话描述 | 是 |
#' Description |
空行后的段落 | 是 |
@param |
参数文档 | 是 |
@return |
返回值描述 | 是(CRAN 要求) |
@examples |
使用示例 | 强烈建议 |
@export |
添加至 NAMESPACE | 是,用于公开 API |
@family |
分组相关函数 | 建议 |
@seealso |
交叉引用 | 可选 |
@keywords internal |
标记为内部函数 | 用于不导出的文档 |
预期结果: 已识别适合该函数类型的所有必需标签。导出函数至少包含 @param、@return、@examples 和 @export。
失败处理: 若某标签不熟悉,查阅 roxygen2 文档 了解用法和语法。
第 3 步:记录数据集
创建 R/data.R:
#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#' \item{date}{Date of observation}
#' \item{city}{City name}
#' \item{temp_c}{Temperature in Celsius}
#' \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"
预期结果: R/data.R 包含每个数据集的 roxygen 块,@format 描述数据结构,@source 提供数据来源。
失败处理: 若 R CMD check 警告存在未记录的数据集,确保引号中的字符串(如 "city_temperatures")与 usethis::use_data() 保存的对象名称完全匹配。
第 4 步:记录包本身
创建 R/packagename-package.R:
#' @keywords internal
"_PACKAGE"
## usethis namespace: start
## usethis namespace: end
NULL
预期结果: R/packagename-package.R 存在,包含 @keywords internal 和 "_PACKAGE" 哨兵字符串。运行 devtools::document() 后生成 man/packagename-package.Rd。
失败处理: 若 R CMD check 报告缺少包文档页,确认文件命名为 R/<packagename>-package.R 且包含 "_PACKAGE" 字符串。
第 5 步:处理特殊情况
带点号函数名(S3 方法):
#' @export
#' @rdname process
process.myclass <- function(x, ...) {
# S3 method
}
使用 @inheritParams 复用文档:
#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
# implementation
}
使用 .data 代词修复"无可见绑定"警告:
#' @importFrom rlang .data
my_function <- function(df) {
dplyr::filter(df, .data$column > 5)
}
预期结果: 特殊情况(S3 方法、继承参数、.data 代词)的文档处理正确。@rdname 将 S3 方法合并,@inheritParams 复用参数文档而无需重复。
失败处理: 若 R CMD check 警告"no visible binding for global variable",添加 #' @importFrom rlang .data,或作为最后手段使用 utils::globalVariables()。
第 6 步:生成文档
devtools::document()
预期结果: man/ 目录已用每个文档对象的 .Rd 文件更新。NAMESPACE 已重新生成,包含正确的导出和导入条目。
失败处理: 检查 roxygen 语法错误。常见问题:\describe{} 中括号未闭合、某行缺少 #' 前缀、标签名无效。修复后重新运行 devtools::document()。
验证清单
- 每个导出函数均有
@param、@return和@examples -
devtools::document()运行无错误 -
devtools::check()无文档相关警告 -
@family标签正确分组相关函数 - 示例运行无错误(使用
devtools::run_examples()测试)
常见问题
- 缺少
@return:CRAN 要求所有导出函数记录返回值 - 示例需要网络或认证:用
\dontrun{}包裹并注释说明原因 - 示例过慢:对能运行但对 CRAN 而言耗时过长的示例使用
\donttest{} - roxygen 中使用 Markdown:在 DESCRIPTION 中启用
Roxygen: list(markdown = TRUE) - 忘记运行
devtools::document():man 页面是生成的,而非手写的
相关技能
create-r-package— 包含 roxygen 配置的包初始化write-testthat-tests— 为已记录的函数编写测试write-vignette— 函数参考之外的长篇文档submit-to-cran— CRAN 对文档的要求