如何在roxygen2中复用并扩展函数示例模板？

以下是几种可行的规范方案，解决继承并扩展函数示例的问题：

方案一：复用示例生成函数 + @eval #

1. 在包的内部辅助脚本（如R/roxygen-utils.R）中定义生成基础示例的函数，返回包含示例代码的字符串：

# 不导出，仅用于roxygen文档生成
generate_f_examples <- function() {
  '
  # 函数f的基础示例
  x <- 1:10
  result_f <- f(x)
  print(result_f)
  '
}

2. 函数f的roxygen文档中调用该函数生成示例：

#' 计算输入向量的和
#'
#' @eval generate_f_examples()
#' @export
f <- function(x) {
  sum(x)
}

3. 函数g的roxygen文档中，先调用生成f示例的函数，再追加专属代码：

#' 计算输入向量和的两倍
#'
#' @eval generate_f_examples()
#' @examples
#' # 函数g的扩展示例
#' result_g <- g(x)
#' print(result_g)
#' @export
g <- function(x) {
  f(x) * 2
}

方案二：使用roxygen2模板 #

1. 在包根目录创建man-roxygen文件夹，新建example-f.R模板文件，写入f的示例内容：

#' @examples
#' # 函数f的示例
#' x <- 1:10
#' result_f <- f(x)
#' print(result_f)

2. 函数f的文档引用该模板：

#' 计算输入向量的和
#'
#' @template example-f
#' @export
f <- function(x) {
  sum(x)
}

3. 函数g的文档先引用模板，再补充扩展示例：

#' 计算输入向量和的两倍
#'
#' @template example-f
#' @examples
#' # 函数g的扩展示例
#' result_g <- g(x)
#' print(result_g)
#' @export
g <- function(x) {
  f(x) * 2
}

roxygen2会自动合并模板中的@examples与当前文档的@examples内容。

方案三：引用独立示例文件 #

1. 在inst/examples文件夹下创建example_f.R，写入f的示例代码：

# 函数f的示例
x <- 1:10
result_f <- f(x)
print(result_f)

2. 函数f的文档引用该文件：

#' 计算输入向量的和
#'
#' @example inst/examples/example_f.R
#' @export
f <- function(x) {
  sum(x)
}

3. 函数g的文档先引用f的示例文件，再添加扩展代码：

#' 计算输入向量和的两倍
#'
#' @example inst/examples/example_f.R
#' @examples
#' # 函数g的扩展示例
#' result_g <- g(x)
#' print(result_g)
#' @export
g <- function(x) {
  f(x) * 2
}

注意事项 #

• 确保示例中定义的变量（如x）在后续扩展代码中可被正常访问。
• 用于生成示例的内部函数不要导出，避免污染包的命名空间。
• 模板文件需放在man-roxygen目录下，roxygen2会自动识别该路径。

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