Question

在我的新CRAN程序包中，我有10个数据帧，这些数据帧在data /文件夹中有10种左右的各种类型的列。类型是字符串，整数，浮点数，布尔值等。

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

类似：makeDocs（游戏）

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

我担心如果手动操作，可能会出错（〜100列），或者如果名称更改，经常不断地手动重新编辑内容。

我找到了有关记录数据集的绝佳答案 How can I document data sets with roxygen?

...但是这不能解决我如何自动生成这些评论？

Answer 1

从帧名称列表开始，然后像这样的简单介绍：

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 2

我从上面的答案中提取了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")
    }

Answer 3

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

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

> 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生成#'行，当它们放置在.Rd文件中的适当位置时，这些行与生成经过氧化处理的.R文件兼容。请参阅包装中的其他功能，这些功能可以将这些行自动放置到正确的位置。

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

3 个答案: