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?

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.