使用带有 roxygen2 的 @example 标记时的文件位置答案

【问题标题】：Location of files when using @example tag with roxygen2使用带有 roxygen2 的 @example 标记时的文件位置
【发布时间】：2014-09-30 10:05:33
【问题描述】：

使用 roxygen2 记录函数时，可以将示例放在单独的文件中。

请看这里：http://r-pkgs.had.co.nz/man.html “您可以将示例放在单独的文件中，然后使用 @example path/relative/to/packge/root 将它们插入到文档中，而不是将示例直接包含在文档中。”

这里：http://roxygen.org/roxygen2-manual.pdf

例如

#' Add together two numbers.
#' 
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @example /path/to/example/add.R
add <- function(x, y) {
  x + y
}

我的问题是：应该使用什么路径来存储示例 R 文件？

【问题讨论】：

我认为 /inst/ 移动到 / 时安装包？如果文档已经构建，我想这并不重要？
是的，inst/examples 应该移动到 examples，然后我认为您可以在文档中引用 /examples。
OK inst/examples 运行良好。我可以在源代码中引用 /inst/examples/file.R，然后使用 devtools::document() 创建文档。 /inst/examples 移动到 /examples，但我认为这无关紧要，因为文档已经构建...
我无法确定这是否是个好主意。它使运行您的示例变得更容易一些，但 roxygen 的全部意义不在于您将文档放在定义函数的位置旁边吗？

标签： r roxygen2

【解决方案1】：

roxygen 中使用的示例的适当位置是：

inst/examples/

那么氧气线应该是：

#' @example inst/examples/add.R

这是好的做法吗？我认为是，因为：

在开发过程中可以更轻松地运行、修改和测试示例
它可以（至少在原则上）在文档的不同位置重复使用示例，例如在小插曲中

【讨论】：

当我有很多行用于我想要保留的带有缩进的示例时，我发现它很有用。大多数时候我仍然使用@examples。