0Pricing
R Academy · 课时

使用 roxygen2 编写函数文档

编写 @param、@return、@examples 和 @export 标签以自动生成文档

使用 roxygen2 编写函数文档 是 CoddyKit 上的免费 R Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 R Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 R Academy 课程共包含 4 节课。

什么是 roxygen2？

roxygen2 让您可以直接在函数上方编写 R 文档，形式为以 #' 开头的特殊格式注释。运行 devtools::document() 时，roxygen2 会解析这些注释，生成 man/*.Rd 文件，并自动更新 NAMESPACE。

最小 roxygen2 代码块

最简单的文档代码块至少需要标题和描述。第一句（截至第一个句号或空行）会成为标题。后续段落会成为描述。

# R/add.R
#
# #' Add two numbers
# #'
# #' Computes the sum of x and y. Both arguments must be numeric.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@title 和 @description 标签

当首段约定不足以满足需求时，请使用明确的 @title 和 @description 标签 — 例如，标题必须不同于函数名，或描述包含多个段落时。

# #' @title Safe Addition of Numeric Values
# #' @description
# #' Adds two numeric vectors element-wise.
# #' Returns NA where either input is NA.
# #' Useful for financial calculations where NA propagation matters.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@param — 编写参数文档

#' @param name Description 用于记录一个函数参数。每个参数使用一行 @param。描述应说明参数的预期类型以及该参数控制的内容。

# #' Add two numbers
# #'
# #' @param x A numeric vector. The first operand.
# #' @param y A numeric vector. The second operand. Must be the same length as x
# #'   or length 1 (recycled).
# #'
# #' @export
# add <- function(x, y) {
#   if (!is.numeric(x) || !is.numeric(y)) stop('x and y must be numeric')
#   x + y
# }

@return — 记录返回值

#' @return Description 描述函数返回的内容。请说明返回值的类型、类和结构。这是提交到 CRAN 所必需的。

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of the same length as the longer of x or y,
# #'   containing the element-wise sums.
# #'
# #' @export
# add <- function(x, y) x + y

@examples — 可运行的代码示例

#' @examples 提供会显示在帮助页中，并由 R CMD check 运行的代码。示例必须在 5 秒内完成，且不能依赖外部资源（网络、文件）。每一行都是普通的 R 代码 — 无需特殊前缀。

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of element-wise sums.
# #' @examples
# #' add(1, 2)
# #' add(c(1, 2, 3), c(10, 20, 30))
# #' add(0, -5)
# #' @export
# add <- function(x, y) x + y

@export — 公开函数

#' @export 告诉 roxygen2 将函数添加到 NAMESPACE，使程序包用户可以使用它。没有 @export 的函数属于内部函数 — 可以在程序包内部调用，但用户不能调用（除非使用 :::）。

# Public function — exported:
# #' @export
# add <- function(x, y) x + y
#
# Internal helper — not exported:
# check_numeric <- function(x) {
#   if (!is.numeric(x)) stop('Expected numeric')
# }
#
# After devtools::document(), NAMESPACE will contain:
# export(add)
# but NOT check_numeric

@importFrom — 导入函数

#' @importFrom pkg fn1 fn2 会从程序包中导入指定函数到您的命名空间，这样您就可以不加 pkg:: 前缀直接调用它们。请谨慎使用 — 明确写出 pkg::fn() 更清晰，也能避免命名空间污染。

# Option 1 — @importFrom (adds to NAMESPACE, no pkg:: needed):
# #' @importFrom stringr str_trim str_to_lower
# clean <- function(x) str_to_lower(str_trim(x))
#
# Option 2 — explicit :: (recommended for clarity):
# clean <- function(x) {
#   stringr::str_to_lower(stringr::str_trim(x))
# }
#
# Both work; prefer Option 2 to keep NAMESPACE minimal

devtools::document() 工作流

编辑 roxygen2 注释后，调用 devtools::document()（Ctrl+Shift+D）以重新生成 man/*.Rd 并更新 NAMESPACE。然后使用 ?add（在 load_all() 之后）查看帮助页，确认其显示正确。

# Full documentation cycle:
# 1. Edit roxygen2 comments in R/add.R
# 2. devtools::document()     # regenerate man/ and NAMESPACE
# 3. devtools::load_all()     # reload package
# 4. ?add                     # preview the help page
# 5. devtools::check()        # ensure no documentation errors

在一个页面记录多个函数

使用 #' @rdname shared_name 将多个相关函数合并到同一个帮助页中。主函数使用完整的 roxygen2 代码块；辅助函数只需要 @rdname 和 @export。

# R/arithmetic.R
#
# #' Basic Arithmetic
# #' @param x,y Numeric vectors.
# #' @return A numeric vector.
# #' @examples
# #' add(1, 2); subtract(5, 3)
# #' @export
# add <- function(x, y) x + y
#
# #' @rdname add
# #' @export
# subtract <- function(x, y) x - y

其他实用标签

用于完善文档的其他 roxygen2 标签：

  • #' @seealso \code{\link{other_fn}} — 交叉引用
  • #' @note — 在描述后添加额外说明
  • #' @author Name — 函数作者
  • #' @keywords internal — 从程序包索引中隐藏，但保留帮助页
  • #' @family group_name — 在帮助中将相关函数分组
# #' Add two numbers
# #' @param x,y Numeric vectors.
# #' @return Numeric vector.
# #' @seealso \code{\link{subtract}} for the inverse operation.
# #' @family arithmetic
# #' @examples
# #' add(1, 1)
# #' @export
# add <- function(x, y) x + y

快速检查：@export 标签

R 程序包中的函数有 roxygen2 文档，但没有 #' @export 标签时，会发生什么？

roxygen2 文档回顾

完善 R 程序包文档所需的核心 roxygen2 标签：

  • #' @title / 第一行 — 函数标题
  • #' @description — 详细描述
  • #' @param name Description — 记录每个参数
  • #' @return Description — 描述返回值
  • #' @examples \n code — 可运行的示例（由 R CMD check 检查）
  • #' @export — 添加到 NAMESPACE（使函数公开）
  • #' @importFrom pkg fn — 导入指定函数
  • 运行 devtools::document() 以重新生成 man/ 和 NAMESPACE

常见问题解答

「使用 roxygen2 编写函数文档」课时是免费的吗？

是的 — 「使用 roxygen2 编写函数文档」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 R Academy 课程的其余内容，请升级到 CoddyKit PRO。 R Academy 课程共包含 4 节课。

「使用 roxygen2 编写函数文档」这节课中我会学到什么？

编写 @param、@return、@examples 和 @export 标签以自动生成文档 你通过在浏览器中直接运行的动手代码来练习 R Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 R Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 R Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「使用 roxygen2 编写函数文档」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 R Academy 课中编写并运行代码吗？

能。每节 R Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 使用 usethis 和 devtools 组织软件包结构
  2. 使用 roxygen2 编写函数文档
  3. 使用 testthat 进行单元测试
  4. CRAN 提交与软件包维护
← 返回 R Academy