如何为R包roxygen2的@examples自动生成控制台输出？

方法一：利用devtools工具生成带输出的示例 #

1. 先在函数的roxygen注释中写好纯R代码示例（不要手动添加#>输出）：

#' 计算向量的平均值
#' @param x 数值向量
#' @return 向量的平均值
#' @examples
#' x <- 1:5
#' mean(x)
#' @export
my_mean <- function(x) {
  mean(x)
}

2. 在R控制台运行devtools::run_examples("my_mean")，该命令会执行示例代码并输出带#>标记的完整内容，示例输出如下：

#> x <- 1:5
#> mean(x)
#> [1] 3

3. 将这段输出复制替换到原@examples部分即可。后续代码变更时，重复此步骤就能快速更新输出内容。

方法二：通过脚本自动生成并更新注释 #

如果想实现完全自动化，可以编写一段小脚本，自动捕获示例代码的执行输出并替换roxygen注释：

# 指定要处理的函数名
func_name <- "my_mean"

# 读取函数文件并提取现有示例代码
func_file <- paste0("R/", func_name, ".R")
file_content <- paste(readLines(func_file), collapse = "\n")
roc_obj <- roxygen2::roc_proc_text(roxygen2::rd_roc(), file_content)[[1]]
current_examples <- roc_obj$examples

# 执行示例代码并捕获输出
output <- capture.output(eval(parse(text = current_examples)))

# 整理成带#>的格式
formatted_lines <- c(strsplit(current_examples, "\n")[[1]], output)
formatted_output <- paste0("#> ", formatted_lines)

# 替换原文件中的@examples块（需根据实际文件结构调整替换逻辑）
new_content <- gsub(
  pattern = "@examples\n(.*?)(?=@|$)",
  replacement = paste0("@examples\n", paste(formatted_output, collapse = "\n")),
  x = file_content,
  perl = TRUE
)

# 写入更新后的内容
writeLines(new_content, func_file)

注意事项 #

• 禁止在@examples中使用R Markdown代码块（如````{r}`），R CMD check会将其视为纯R代码执行，引发语法错误。
• 确保示例代码可重复执行，若涉及随机数，需提前设置种子（set.seed()）避免输出波动。

内容的提问来源于stack exchange，提问作者Greg