你能分享 rOxygen2 函数之间的例子吗？

Question

我知道可以使用 rOxygen 使用 @describeIn 或 @rdname 标签将多个函数分组在同一文档下。这对于具有类似 purpose/syntax.

的函数组来说很好

但是，我正在编写一个程序包，其中一组函数几乎总是作为工作流的一部分执行。为了让事情更清晰，我想用一个例子来说明这个工作流程，并为所有涉及的功能展示它。

我需要将这些函数保留在它们单独的文档页面中，因为它们中的每一个都有非常不同的目的、参数并且需要一个相当广泛的文档。我不想通过将所有内容组合在一起来混淆 reader。

这个可以吗？例如，我可以拥有一个包含示例代码的文件并将其包含在所有功能文档中吗？

为了以防万一，我在下面包含了一些虚拟代码。

#' function1
#' 
#' This does stuff
#' 
#' @param a,b a and b
#' @return c
#' @export
#' @examples 
#' # step 1 : do this
#' C <- function1(a,b)
#' 
#' # step 2 : do that
#' D <- function2(C, e, f)
#' 
#' # step 3 : profit.
function1 <- function(a,b){
  return(a+b)
}

#' function2
#' 
#' This also does stuff
#' 
#' @param C could be from function1
#' @param e,f e and f
#' @return d
#' @export
#' @examples 
#' # step 1 : do this
#' C <- function1(a,b)
#' 
#' # step 2 : do that
#' D <- function2(C, e, f)
#' 
#' # step 3 : profit.
function2 <- function(C, e, f){
  return(C+e+f)
}

Answer 1

我找到了一种方法，通过使用 Roxygen 的 @eval 标签并将我的示例存储在返回示例代码的函数中。

所以在一个包中，你会有一个像这样的 shared_examples.R 文件：

function_examples <- function()
{
  ex <- "
@examples
# step 1 : do this
C <- function1(a,b)

# step 2 : do that
D <- function2(C, e, f)

# step 3 : profit.
"
  return(strsplit(ex, split = "\n")[[1]]) # needed to have line jumps in the doc
}

然后，您的实际功能文档将如下所示：

#' function1
#' 
#' This does stuff
#' 
#' @param a,b a and b
#' @return c
#' @export
#' @eval function_examples()
function1 <- function(a,b){
  return(a+b)
}

#' function2
#' 
#' This also does stuff
#' 
#' @param C could be from function1
#' @param e,f e and f
#' @return d
#' @export
#' @eval function_examples()
function2 <- function(C, e, f){
  return(C+e+f)
}

现在，该示例在这两个函数之间共享！

我发现这使得集中示例（或函数之间的任何共享文档）变得非常容易，而不必在更新时大费周章地重复所有内容。

Answer 2

我认为这是一种更合适的方式。

你的例子可以

存在于@examples 标签之后
存在于您从文档中获取的 R 脚本中，即

#' @example man/examples/foo.R

来源：https://www.r-bloggers.com/code-examples-in-the-r-package-manuals/

你能分享 rOxygen2 函数之间的例子吗？

Can you share examples between functions with rOxygen2?

r

r-package

roxygen2