devtools::document vs roxygen2::roxygenize [关闭]答案

【问题标题】：devtools::document vs roxygen2::roxygenize [closed]devtools::document vs roxygen2::roxygenize [关闭]
【发布时间】：2014-08-03 11:14:52
【问题描述】：

前段时间我在某处读到 devtools::document 比 roxygen2::roxygenize 更好的“复杂包/sitations”（这是我记得的），但不幸的是我现在找不到链接，我没有那个时候加深。

查看相应的帮助页面，我不清楚如何，所以我的问题是：如果有时最好使用devtools::document 而不是 roxygen2::roxygenize，是什么时候？适合哪种套餐？

谢谢，卢卡

【问题讨论】：

就在pkg docs：roxygen2::roxygenise() just sources all files in the R/ directory，devtools::document() sources all files in the R/ directory, compiles source code in the src/ directory, loads data in the data/ directory and generally does an accurate job of simulating package loading。 “如果你有一个简单的包，你可以使用 roxygenise()，但对于更复杂的，我建议你使用 document()。”

标签： r devtools roxygen2

【解决方案1】：

你在回忆roxygen2 README：

Roxygen 对您的源代码进行实时分析：它会加载包中的所有代码，因此它可以使用 R 环境中的值创建文档，而不仅仅是源代码。然而，模拟包加载一般来说是相当棘手的，所以有两种方法可以用 roxygen 来完成：

roxygen2::roxygenise() 只是获取 R/ 目录中的所有文件

devtools::document() 对 R/ 目录下的所有文件进行源码化，在 src/ 目录下编译源代码，在 data/ 目录下加载数据，通常可以准确地模拟包加载。

如果你有一个简单的包，你可以使用 roxygenise()，但是对于更复杂的，我建议你使用 document()。

您可以在document 调用roxygenise（通过devtools:::document_roxygen3）中看到这种区别：

> document
function (pkg = ".", clean = FALSE, roclets = c("collate", "namespace", 
    "rd"), reload = TRUE) 
{
    if (!is_installed("roxygen2", 3)) {
        stop("Please install latest roxygen2", call. = FALSE)
    }
    pkg <- as.package(pkg)
    message("Updating ", pkg$package, " documentation")
    man_path <- file.path(pkg$path, "man")
    if (!file.exists(man_path)) 
        dir.create(man_path)
    if (clean) {
        file.remove(dir(man_path, full.names = TRUE))
    }
    if (!is_loaded(pkg) || (is_loaded(pkg) && reload)) {
        try(load_all(pkg, reset = clean))
    }
    document_roxygen3(pkg, roclets)
    clear_topic_index(pkg)
    invisible()
}
<environment: namespace:devtools>

> devtools:::document_roxygen3
function (pkg, roclets) 
{
    with_envvar(r_env_vars(), with_collate("C", roxygen2::roxygenise(pkg$path, 
        roclets = roclets, load_code = pkg_env)))
}
<environment: namespace:devtools>

【讨论】：

大部分区别不在这里——它在于 devtools 如何模拟包加载。
@hadley 随时发布更正确的答案或编辑您想要的任何内容。
在 load_all() 的定义中缺少复制（以及 it 调用的所有 devtools:::* 函数）我不明白你怎么能做到这么多更清晰。