roxygen2 8.0.0

I’m pleased to announce that roxygen2 8.0.0 is now on CRAN. roxygen2 turns specially formatted comments in your R code into the .Rd files that power R’s help system. You can install it with:

1

install.packages("roxygen2")

This release has been a long time in the making and includes well over a hundred bug fixes and improvements. This post covers the highlights: new support for S7, a raft of improvements to R6 documentation, a more natural way to configure roxygen2 in your DESCRIPTION, the changes to rendered .Rd files you’re most likely to see, and some other minor improvements, and a bunch of new vignettes. You can read the full list of changes in the release notes .

1

library(roxygen2)

Documenting S7#

The headline feature is initial support for S7 . S7 is a new object-oriented programming system built to be a successor to S3 and S4. It’s been designed and implemented collaboratively by the R Consortium Object-Oriented Programming Working Group, which includes representatives from R-Core, Bioconductor, tidyverse/Posit, and the wider R community. S7 is still a work in progress, but it is useful today, and adding roxygen2 support makes it easier to use in packages.

roxygen2 now supports documenting S7 generics, classes, and methods:

Generics are documented just like regular functions.
Classes are documented like regular functions (because S7 constructors are functions), but you can also use @prop to document properties that aren’t constructor parameters. If you document several related classes on the same page, @prop ClassName@prop_name description lets you group properties by class.
Methods registered with method(generic, class) <- fn are picked up automatically, and roxygen2 generates the right usage and aliases for you.

Read vignette("rd-S7") for a full rundown, and please let us know if you discover any issues or have suggestions for improvement!

A cleaner home for configuration#

roxygen2 has historically been configured through a Roxygen: field in DESCRIPTION, with a separate RoxygenNote field recording the version. This release introduces a more natural home using the Config/roxygen2/ namespace that packages like testthat and lifecycle have adopted:

1
2
3
4
5
6
7


# before
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2

# after
Config/roxygen2/markdown: TRUE
Config/roxygen2/version: 8.0.0

The old fields still work, and roxygen2 will quietly migrate RoxygenNote the next time you run devtools::document(). Over time, devtools and usethis will switch to the new form by default.

Rendering tweaks#

When you re-document your package for the first time with roxygen2 8.0.0, you might notice some small differences in the rendered output. The most commonly encountered changes are:

All generated cross-reference links now go through the same code path and share a single style, e.g. \code{\link[=compose]{compose()}}.
Links to external packages now use the topic alias rather than the .Rd filename. This brings roxygen2 into alignment with current CRAN best practices.
Tags that typically expect a single line of input now warn if you spread them across multiple lines. This catches a common class of silent mistakes, e.g. a @name or @rdname with no content that quietly included the next line of the block. This will create warnings for some existing legitimate uses, but I think the payoff (eliminating problems that are otherwise very hard to spot) is worth it.
People with both "aut" and "cre" roles now appear in both the Authors and Maintainer sections of package documentation.

Other important changes#

roxygen2 now requires R 4.1 and no longer depends on purrr, stringr, or stringi. Those last two are the big win because it means that stringi is now gone from the complete devtools dependency graph, making it easier to install for folks on constrained Linux images.

There’s a new helper, needs_roxygenize(), that tells you whether your .Rd files are out of date by comparing modification times against their sources. It’s much cheaper than running roxygenize() just to find out nothing has changed, which makes it a good fit for pre-commit hooks or CI checks.

Finally, parameter inheritance has gained a small but very useful feature: @inheritParams now supports filtering, just like @inheritDotParams. If you only want to inherit a subset of arguments from another function, you can now list them explicitly:

1

#' @inheritParams other_fn x y

Or exclude the ones you don’t want:

1

#' @inheritParams other_fn -z

Speaking of @inheritDotParams, it now also works more like @inheritParams: it inherits documented parameters rather than formal arguments. This may introduce new false positives (replacing the old approach’s false negatives), which you can prevent by explicitly listing the argument names to inherit.

New vignettes#

roxygen2’s own documentation has had a significant tidy-up. The old vignette("rd-other") has been broken into focused vignettes — vignette("rd-datasets"), vignette("rd-packages"), vignette("rd-S3"), vignette("rd-S4"), and vignette("rd-R6") — with the new vignette("rd-S7") joining them. The main vignette("rd") has been renamed to vignette("rd-functions"), and the “getting started” content has moved to vignette("roxygen2").

vignette("rd-S3") has also been rewritten with clearer guidance for documenting S3 generics, classes, and methods, including how to use the new doclisting package to automatically list methods for a generic — a long-standing pain point for generics with methods in multiple packages. You can also use doclisting with S4 and S7 generics.