roxygen2 not fully updating DESCRIPTION file

Question

I'm making my first package rlandscape, using Roxygen2 and trying to follow the plain Roxygen vignette since Roxygen2 doesn't have one.

As in the vignette (page 3), I created a file called rlandscape-package.R that contains nothing but package documentation. In the vignette, they say

each Roxygen description block must be followed by a statement, even header material that describes a le or package in lieu of a specific function. roxygen() is provided as a NOOP (null statement) to stand in for such cases.

but if I follow the description block with roxygen() a call to package.skeleton produces Error in eval(expr, envir, enclos) : could not find function "roxygen". So I've tried leaving the roxygen() call out entirely as well as replacing it with NA, both of which seem to produce the same results: package.skeleton() works successfully (including rlandscape-package.R as one of the code_files arguments), and I can then roxygenize

> roxygenize("rlandscape", roxygen.dir = "rlandscape")
Updating collate directive in  /Users/Gregor/Dropbox/rlandscape/rlandscape/DESCRIPTION 
Updating namespace directives
Writing plot.landscape.Rd
Writing rland.Rd
Writing rland.gui.Rd
Writing makePoints.Rd
Writing rCluster.Rd
Writing rlandscape-package.Rd
Writing rlandscape.Rd

which seems to run successfully, but the DESCRIPTION file has the "Collate" field appended, but is otherwise unchanged from what package.skeleton created. Why isn't the rest of the description file updated?

Abisha

One other thing. With roxygen2, for documentation blocks which aren't followed by code, I believe the recommendation is put a NULL (where you would've put a call to roxygen() if using the older roxygen package). – Lorettelorgnette

Answer 1

roxygen2 is working just as intended, but I experienced the same confusion when I first used it to document a package. The important bit to understand is that there are a couple of different package-describing files in the mix.

• When the roxygen markup in rlandscape-package.R is processed, it produces a file rlandscape-package.Rd in the man directory of your source package. This in turn produces the documentation you see when you type ?rlandscape or ?"rlandscape-package".

• The DESCRIPTION file in the top directory of your source tree is a completely separate beast. Although it happens to produce a help file that you can see (via help(package="rlandscape")), it has many other more important roles in directing package production. The only way that it is touched/affected by roxygen2 is that the collate_roclet() function (executed when you roxygenize() your package) will perform merges with the Collate field in a pre-existing DESCRIPTION file (as describe on p 10 of this pdf).

The main take home message is that even when using roxygen2, if you want to make changes to your DESCRIPTION file, you'll need to do it by directly editing it.

Alopecia

Almost 2 years later, it'd be worth adding that the devtools package now provides functions like create_description for automatically creating description files. – Abisha

As 2019 and version 2.2.1, there is no function create_description – Hives

Answer 2

I had the same problem. And I believe the reason for that is to push the changes after commit ing from the Version Control under Tools. I guess you need to commit first, set your credentials then try to push the package using r console usethis::use_github(protocol = "https"), and if you created already a repo delete it and try this again. You can also check this video 14th minute to see how DESCRIPTION updates.

Parclose