devtools::document vs roxygen2 2：：roxygenize

Question

不久前，我在某个地方读到devtools::document比roxygen2::roxygenize更适合“复杂的包/站点”(这是我记得的)，但不幸的是，我现在找不到链接，也没有深入到那个时候。

查看各自的帮助页，我不清楚如何使用，所以我的问题是:如果有时使用devtools::document而不是roxygen2::roxygenize更好，当情况是这样的时候？什么样的包裹？

谢谢你，卢卡

Answer 1

你在回忆 README

RO2对源代码进行实时分析:它加载包中的所有代码，因此它可以使用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>