是否可以设置一个全局标志以在 ROxygen 文档旁边提供代码？答案

【问题标题】：Is there a global flag that can be set to provide code alongside ROxygen documentation?是否可以设置一个全局标志以在 ROxygen 文档旁边提供代码？
【发布时间】：2013-03-03 15:53:48
【问题描述】：

我教了一门课，让学生使用我编写的包。现在课程即将结束，我想为他们提供每个函数的代码，这些代码与函数的文档内联。我可以设置一个全局标志来完成此操作吗？某种代码破解？

【问题讨论】：

那么您希望函数代码显示在代码本身的帮助文件中吗？为什么？
这听起来更像是“文学编程”而不是“可重复的研究”：rpubs.com/bbolker/3153
@Dason：是的，这就是我想要的。了解我的用户后，我认为他们会发现在 PDF 中找到他们想要的脚本比在一堆分散的 ROxygen 标记脚本甚至单个 ROxygen 标记脚本中更容易。
@BenBolker：是的，这是一个有文化的编程目标。我在您的页面上看到了stackoverflow.com/questions/2545136/… 的链接。然而，共识似乎是它没有死。但是，我想我看到了可能 ROxygen 本身并不是为“文学编程”而设计的区别。我知道这不是典型的用例。我的希望是，由于它是一个类似的用例，因此可以诱使 ROxygen 提供所需的结果。
进一步阅读，似乎如果我有更多的远见，我会一开始就用 Sweave 编写所有内容。奇怪的是，这就是我开始记录我的函数的方式，但是当我决定开始将它们放入一个包中时，我改用 ROxygen ......当时我认为这是一种改进。

标签： r roxygen literate-programming roxygen2

【解决方案1】：

您可以使用 brew 包预处理您的 R 文件，例如

文件'foo-tmp.r'

##' a function that doesn't do much 
##'
##' @title foo
##' @param x 
##' @param y 
##' @param z 
##' @return error message
##' @author Baptiste 
##' @examples
##' dontrun{
#<%= cat(paste0("##'", getSrcref(foo), "\n")) %> ##' }
foo <- function(x,  y,  z){
    rnorm(10) == 1
    # inline comment
    .NotYetImplemented()
    " other stuff"
    return(FALSE)
  }

然后处理文件生成foo.r

source("foo-tmp.r") # to know what the function is
brew("foo-tmp.r", "foo.r")

结果输出：

##' a function that doesn't do much 
##'
##' @title foo
##' @param x 
##' @param y 
##' @param z 
##' @return error message
##' @author Baptiste 
##' @examples
##' dontrun{
###'function(x,  y,  z){
 ##'    rnorm(10) == 1
 ##'    # inline comment
 ##'    .NotYetImplemented()
 ##'    " other stuff"
 ##'    return(FALSE)
 ##'  }
 ##' }
foo <- function(x,  y,  z){
    rnorm(10) == 1
    .NotYetImplemented()
    " other stuff"
    return(FALSE)
  }

【讨论】：

其实你并不需要这两个文件，brew() 可能不会对普通的 R 文件做任何事情，所以你可以愉快地覆盖而不会丢失。
但是覆盖文件本身可能会导致函数和文档过时的情况。再说一次，如果一个人正在制作这个文档，然后再也不修改函数，那也没关系......
这个解决方案总比没有好，但仍然不像我希望的那样简洁。有没有一种方法可以使用模板标签来实现所需的结果，而无需更改要记录的每个函数的代码？

【解决方案2】：

见this related question。没有全局标志或解决方案。 @baptiste's 是最好的。答案设置为社区 wiki，以防这种情况发生变化。

【讨论】：