R包构建未记录的代码对象答案

【问题标题】：R package build Undocumented code objectsR包构建未记录的代码对象
【发布时间】：2014-08-17 12:54:02
【问题描述】：

我编写了一个用于与电子病历集成的 R 包。我想我已经在DESCRIPTION文件中正确添加了导入和依赖项，并通过roxygen2记录了所有内容，但是在我的三个函数（它们都在同一个文件中）上，当我运行devtools::check（“。” ):

* checking for missing documentation entries ... WARNING
Undocumented code objects:
  'add_to_database' 'database' 'import_CPRD_data'
All user-level objects in a package should have documentation entries.

我认为我已经以与我所有其他功能相同的方式记录了这些内容，这些功能都很好。这是 roxygen2 文档中的一个有问题的函数：

#' Wrapper for dbconnect
#' 
#' Connects to a SQLite database or creates one if it does not already exist
#' 
#' If the '.sqlite' file extension is ommited from the dbname argument it is automatically added.
#'
#' @export
#' 
#' @param dbname character name path to database file
#' @return SQLiteConnection object
#' @examples \dontrun{
#' db <- database("mydb")
#' }
database <- function(dbname){
    if(!str_detect(dbname, "\\.sqlite$")) {
        dbname <- paste(dbname, "sqlite", sep = ".")
    } 
    dbConnect(SQLite(), dbname)
}

我怎样才能摆脱这个错误？我已将 stringr 和 RSQLite 添加到 DESCRIPTION 文件的依赖部分，它们显示在 NAMESPACE 中，所以我认为这不是导入问题 - 但是我没有记录什么？完整包是here，带有违规功能的文件是here。我查看了编写 R 扩展手册并找不到问题 - 不知道我是否只是因为看而失明 - 但我看不出我在这些函数中所做的与我编写的其他函数有什么不同！

【问题讨论】：

我从 github 克隆了包并运行了devtools::check(".")。 * checking for missing documentation entries ... OK
这很奇怪！你在什么平台上运行？我通过 rstudio 服务器在 Linux 服务器上。我现在会做同样的检查。
也是通过 rstudio 服务器的 linux 服务器
好的，所以克隆构建得很好，但我仍然在工作目录中收到错误。这是一种解脱，但仍然不知道它来自哪里。

标签： r devtools

【解决方案1】：

您使用 roxygen，但很可能您没有在构建时对您的包进行 roxygen 化。

任一调用：

roxygen2::roxygenize('.', roclets=c('rd', 'collate', 'namespace'))

或者，如果您使用 RStudio，编辑项目选项（工具菜单）并在“构建工具”选项卡中检查使用 Roxygen 生成文档。

【讨论】：

谢谢。我在 Rstudio 中运行，当 check() 运行时，文档与 NAMESPACE 一起生成。尝试删除所有 rd 文件并重新检查，但无济于事。所有其他 rd 文件生成正常。
@dspringate 我无法复制它。克隆了 repo，做了 roxygenize (Roxygen 4.0.1) 并且所有的 Rd 都在那里。 Fedora x86_64 上的 R 3.1。
为避免警告，请将 Encoding: UTF-8 添加到您的 DESCRIPTION 文件中。

【解决方案2】：

我在R CMD check 时遇到了类似的问题：

Status: 1 WARNING
checking for missing documentation entries ... WARNING
Undocumented code objects:
  ‘build.log.output’

在逐步删除所有文件后，我找到了原因：.Rbuildignore 文件！它包含（除了其他行）一行

^.*\.log

最后一行使 R 忽略其名称中包含“.log”的所有文件，我的函数被命名为“build.log.output”，这导致 R 忽略生成的文档文件“build.log.output.Rd” Roxygen2 在创建包文件时。

因此R CMD check在包文件中找不到文档！

解决方案：

改进正则表达式以仅忽略真实的日志文件：

^.*\.log$

("$" 表示匹配行尾)。

瞧 :-)

【讨论】：

【解决方案3】：

编辑：

@R Yoda 解决了我的“答案”中所述的问题：它与 .Rbuildignore 和函数名称（更准确地说，函数文档的文件名）之间的冲突有关。

同样的问题。对我来说，这与函数的名称有关。当下面的函数名称为load_rdata（或loadrdata）时，我会收到警告Undocumented code objects: 'load_rdata'。当我将函数重命名为load_rda 时，一切正常。

我知道这是半个问题（为什么会发生这种情况），半个答案（可能是因为函数名称），但我认为这可能会帮助遇到这个问题的人。

#' Load RData file.
#' 
#' @param file An RData file saved via \code{\link[base]{save}}.
#' @return The object save in \code{file}.
#' @references \url{http://stackoverflow.com/a/5577647}
#' @export
load_rdata <- function(file = NULL) {
    env <- new.env()
    nm <- load(file, env)[1]
    env[[nm]]
}

这是来自 sesssionInfo() 的输出，在使用 devtools 1.12.0 和 roxygen2 6.0.0 时可重现。

R version 3.3.2 (2016-10-31)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows >= 8 x64 (build 9200)

locale:
[1] LC_COLLATE=German_Germany.1252  LC_CTYPE=German_Germany.1252    LC_MONETARY=German_Germany.1252
[4] LC_NUMERIC=C                    LC_TIME=German_Germany.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] devtools_1.12.0.9000 roxygen2_6.0.0.9000 

loaded via a namespace (and not attached):
 [1] R6_2.2.0            magrittr_1.5        tools_3.3.2         withr_1.0.2         memoise_1.0.0      
 [6] Rcpp_0.12.9         xml2_1.1.1          stringi_1.1.2       pkgload_0.0.0.9000  digest_0.6.12      
[11] stringr_1.1.0       pkgbuild_0.0.0.9000 commonmark_1.1

【讨论】：

我还发现对我的.R 文件进行小改动，然后调用devtools::load_all(".")，然后调用devtools::document()，然后devtools::check(".") 为我解决了这个问题。在我的 Windows 机器上的驱动器之间移动我的包目录后，我遇到了这个问题。我认为文档没有被正确更新，但是通过做一个小改动，文档确实得到了更新，然后 R CMD 检查通过了。

【解决方案4】：

当我有多个要导出的函数时，我遇到了未记录的代码错误。我认为您需要添加#' @describeIn。这是我的例子。

#' @title Colors Definition
#'
#' @description Define colors with transparency value.
#'
#' @param alpha Transparency value (0-1), default 1.
#'
#' @return hex value of the color
#'
#' @examples
#'   Get_Red(0.5)
#'   Get_Red()
#'
#' @export Get_Red
#' @export Get_Blue
#'

Get_Red <- function(alpha = 1) {
  rgb(228 / 255, 26 / 255, 28 / 255, alpha)
}

#' @describeIn Get_Red Blue color function with transparency value.
Get_Blue <- function(alpha = 1) {
  rgb(55 / 255, 126 / 255, 184 / 255, alpha)
}

【讨论】：

【解决方案5】：

我正在试验玩具foofactors 包装in Hadley Wickam's 书。我的data.R 文件包括：

#' A character string
#'
"MyString"

和fbind.R 有：

#' Print a string
#'
#' Returns the string MyString
#'
#' @export
#'
myString <- function() {
  print(foofactors::MyString)
}

check 抱怨存在未记录的代码和数据。我通过将函数名称更改为theString 来解决此问题。因此，名称似乎不区分大小写，这很奇怪。

【讨论】：

【解决方案6】：

我通过安装 devtools 包修复了同样的错误消息。

就我而言，我在一台新笔记本电脑上创建了一个新软件包，并安装了所有常用的 R 软件包和附件：installr, testthat, roxygen2 以及 rtools 和 MiKteX 等附件工具。在构建包时，我收到了相同的错误消息“检查缺少的文档条目......警告：未记录的代码对象”。但是我通过安装devtools 包完全解决了这个问题。

【讨论】：