r-如何重复使用Roxygen文档中的项目描述

Question

我正在记录R包中的许多数据帧，要么是因为它们是由函数返回的，要么是作为数据包含的。通常，需要为许多数据帧描述相同的列/项如何避免多次复制/粘贴同一商品描述

例如，假设我正在R/data.R:中记录以下数据帧

#' @name OBJ_1
#' @title Object 1
#' @format A data frame with 401 rows and 6 variables:
#' describe{
#'   item{code{feature_ID}}{character, a very carefully defined description}
#'   item{code{col1}}{double, blah}
#'   item{code{col2}}{integer, blah}
#'   item{code{col3}}{character, blah}
#'   item{code{col4}}{integer, blah}
#'   item{code{col5}}{character, blah}
#'}   
"OBJ_1"
#' @name OBJ_2
#' @title Object 2
#' @format A data frame with 333 rows and 5 variables:
#' describe{
#'   item{code{feature_ID}}{character, a very carefully defined description}
#'   item{code{col6}}{double, blah}
#'   item{code{col7}}{integer, blah}
#'   item{code{col8}}{character, blah}
#'   item{code{col9}}{integer, blah}
#'}   
"OBJ_2"

同样，我想记录一个函数返回的数据帧：

#' Some function 
#'
#' @return data frame with one row per feature:
#' describe{
#'   item{code{feature_ID}}{character, a very carefully defined description}
#'   item{code{colx}}{blah}
#'   item{code{coly}}{blah}
#' }
#' 
#' @export
#' 
myFunction = function(){
# do stuff
return(df)
}

在这三种情况下，feature_ID的定义方式相同。是否有任何方法可以在的某个地方定义feature_ID一次，并在Roxygen中使用经过评估的表达式将所需定义插入.Rd文档中？

对于重复的@params，@eval是一种很好的方法，但@eval在另一个Roxygen标签(如@format或@describe(内不起作用。

我也尝试了动态R代码解决方案，但这个：

feature_ID = function(){
"character, a very carefully defined description"
}
...
#'   item{code{feature_ID}}{`r feature_ID()`}

在相应的Rd:中对此进行了评估

item{code{feature_ID}character, a very carefully defined description)`}

而不是：

item{code{feature_ID}{character, a very carefully defined description}

这似乎比任何预期行为都更像是一个bug。。。

由此看来，@templateVar name value似乎很有前景，但我找不到任何关于如何实际实现它的文档。

如果有任何帮助，我将不胜感激！如果/当我们最终想要更改变量的定义时，大量的复制/粘贴感觉像是一种罪恶，而且效率会非常低。

Answer 1

事实证明，使用动态R代码解决方案描述的行为是错误。我使用的是roxygen2版本7.1.2。更新到7.2.1版本解决了这个问题，并为我提供了我想要的解决方案。

下面是一个完整的示例，说明如何在呈现时将文本动态插入Roxygen文档。

1. 在R脚本中定义常用的参数/参数/项，类似于R/define_params.R。您不需要添加Roxygen标记，或者如果添加了，则添加@noRd而不包括@export，这样就不会导出函数，也不会生成相应的.Rd。

   feature_ID = function(){
   "character, a very carefully defined description"
   }
   assay = function(){
   "character, another description I use a lot"
   }
   

2. 使用动态R代码在Roxygen文档中插入字符串，包括内部标记。

   #' Some function 
   #'
   #' @return data frame with one row per feature:
   #' describe{
   #'   item{code{feature_ID}}{`r feature_ID()`}
   #'   item{code{colx}}{blah}
   #'   item{code{coly}}{blah}
   #' }
   #' 
   #' @export
   #' 
   myFunction = function(){
   # do stuff
   return(df)
   }
   

   #' @name OBJ_1
   #' @title Object 1
   #' @format A data frame with 401 rows and 7 variables:
   #' describe{
   #'   item{code{feature_ID}}{`r feature_ID()`}
   #'   item{code{assay}}{`r assay()`}
   #'   item{code{col1}}{double, blah}
   #'   item{code{col2}}{integer, blah}
   #'   item{code{col3}}{character, blah}
   #'   item{code{col4}}{integer, blah}
   #'   item{code{col5}}{character, blah}
   #'}   
   "OBJ_1"
   

3. 使用roxygen2::roxygenise()生成文档
4. 如果你查看.Rd文件，你会发现你的R代码被替换为相应函数中定义的字符串，例如：

   ...
   item{code{feature}}{character, a very carefully defined description}
   item{code{assay}}{character, another description I use a lot}}
   ...