devtools::document vs roxygen2::roxygenize

Question

Some time ago i've read somewhere that devtools::document is better than roxygen2::roxygenize for "complex packages/sitations" (this is what i remember), but unfortunately i can't find the link now and i didn't deepen at that time.

Looking at respective help pages it's not clear to me how, so my question is: if sometime it's better to use devtools::document rather than roxygen2::roxygenize, when it's the case? for which kind of packages?

Thanks, Luca

Answer 1

You're recalling the roxygen2 README:

Roxygen does a live analysis of your source code: it loads all the code in your package, so it can create documentation using values in an R environment, not just source code. However, simulating package loading is rather tricky to do in general, so there are two ways to do it with roxygen:

• 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.

If you have a simple package, you can use roxygenise(), but for anything more complicated, I recommend that you use document().

You can see this distinction in that document calls roxygenise (by way of devtools:::document_roxygen3) after doing a bunch of other stuff:

> 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>