为数据框自动生成 roxygen2 文档的最佳方法是什么？

Question

在我的新 CRAN 包中，我有 10 个数据框，在 data/ 文件夹中每种类型都有 10 列左右。类型有字符串、整数、浮点数、布尔值等。

我需要为每个数据源添加 roxygen2 文档。有没有一种方法可以在给定 data.frame 的情况下自动生成评论块？

类似：makeDocs(games)

#' games
#'  title character
#'  score integer
#'  value numeric
#'  ...

我担心如果我手动执行，我可能会出错（大约 100 列），或者如果名称发生变化，我会不断地手动重新编辑内容。

我找到了这个关于记录数据集的好答案 How can I document data sets with roxygen?

...但这并没有解决我如何自动生成这些 cmets？

Answer 1

您很可能会发现sinewR-package 提供的功能很有用；请参阅here 的 R-bloggers 帖子中提供的示例。

以下示例适用于数据帧和函数，并为它们创建 roxygen 骨架。您自然需要手动修改一些字段，如大写字母所示：

> set.seed(1); dat <- data.frame(first = LETTERS[1:10], second = rnorm(10), third = 1:10)
> fun <- function(x, y) { x + y }
> sinew::makeOxygen(dat)
#' @title DATASET_TITLE
#' @description DATASET_DESCRIPTION
#' @format A data frame with 10 rows and 3 variables:
#' \describe{
#'   \item{\code{first}}{character COLUMN_DESCRIPTION}
#'   \item{\code{second}}{double COLUMN_DESCRIPTION}
#'   \item{\code{third}}{integer COLUMN_DESCRIPTION} 
#'}
#' @details DETAILS
"dat"
> sinew::makeOxygen(fun)
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param x PARAM_DESCRIPTION
#' @param y PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @details DETAILS
#' @examples 
#' \dontrun{
#' if(interactive()){
#'  #EXAMPLE1
#'  }
#' }
#' @rdname fun
#' @export

如您所见，sinew 生成#'-行，当放置在.R-文件中的适当位置时，这些行与生成roxygenized .Rd 文件兼容。查看包中可以将这些线自动放置到正确位置的更多功能。

Answer 2

从框架名称列表开始，然后是这样的快速破解：

frames <- c("iris","mtcars")
unlist(sapply(frames, function(d) c(paste("#'", d), "#' @format data.frame",
                                    gsub("^","#'",capture.output(str(get(d)))),
                                    dQuote(d)),
              simplify=FALSE), use.names=FALSE)
#  [1] "#' iris"                                                                                    
#  [2] "#' @format data.frame"                                                                      
#  [3] "#''data.frame':\t150 obs. of  5 variables:"                                                  
#  [4] "#' $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ..."                            
#  [5] "#' $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ..."                          
#  [6] "#' $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ..."                        
#  [7] "#' $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ..."                        
#  [8] "#' $ Species     : Factor w/ 3 levels \"setosa\",\"versicolor\",..: 1 1 1 1 1 1 1 1 1 1 ..."
#  [9] "\"iris\""                                                                                   
# [10] "#' mtcars"                                                                                  
# [11] "#' @format data.frame"                                                                      
# [12] "#''data.frame':\t32 obs. of  11 variables:"                                                  
# [13] "#' $ mpg : num  21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ..."                          
# [14] "#' $ cyl : num  6 6 4 6 8 6 8 4 4 6 ..."                                                    
# [15] "#' $ disp: num  160 160 108 258 360 ..."                                                    
# [16] "#' $ hp  : num  110 110 93 110 175 105 245 62 95 123 ..."                                   
# [17] "#' $ drat: num  3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ..."                        
# [18] "#' $ wt  : num  2.62 2.88 2.32 3.21 3.44 ..."                                               
# [19] "#' $ qsec: num  16.5 17 18.6 19.4 17 ..."                                                   
# [20] "#' $ vs  : num  0 0 1 1 0 1 0 1 1 1 ..."                                                    
# [21] "#' $ am  : num  1 1 1 0 0 0 0 0 0 0 ..."                                                    
# [22] "#' $ gear: num  4 4 4 3 3 3 3 4 4 4 ..."                                                    
# [23] "#' $ carb: num  4 4 1 1 2 1 4 2 2 4 ..."                                                    
# [24] "\"mtcars\""                                                                                 

然后您可以cat 将其保存到一个文件中，并拥有您需要的大部分内容。

Answer 3

我从他上面的答案中提取了 r2evans 代码并将其变成了一个函数。

makeDoc = function (dataFrame, title = substitute(dataFrame)) {
      output = c(paste("#'", title), "#' @format data.frame", gsub("^","#'",capture.output(str(dataFrame))), dQuote(title))
      cat(output, sep="\n")
    }