roxygen2 7.1.0

  2020/03/11

  r-lib, devtools, roxygen2

  Gábor Csárdi

We’re chuffed to announce the release of roxygen2 7.1.0. roxygen2 allows you to write specially formatted R comments that generate R documentation files (man/*.Rd) and the NAMESPACE file. roxygen2 is used by over 8,800 CRAN packages.

Install the latest version of roxygen2 with:

install.packages("roxygen2")

This is a minor release, with many small improvements and bug fixes, and some new features. This blog post discusses the most important changes. See the full changelog for all changes.

roxygen2 meets knitr

We have been gradually improving roxygen2’s markdown support, and this release has an exciting new markdown feature as well. Starting from roxygen2 7.1.0 you can write inline R code and markdown code fences directly in roxygen2 comments! roxygen2 runs the R code and inserts its output into the documentation.

Inline R code

For running R code inline, use the usual markdown backticks, and prefix the code with r and a space character. roxygen2 interprets the rest of the text within backticks as R code, evaluates it, and replaces the backtick expression with its value. After all such substitutions, the text of the whole tag is interpreted as markdown, as usual.

For example, the following code inserts the date and the R version of the roxygen2 run.

#' roxygen2 created this manual page on `r Sys.Date()` using R version
#' `r getRversion()`.

Code blocks (fences)

Markdown code blocks can be dynamic as well, if you use ```{r} to start them, just like in knitr documents. roxygen evaluates the code, and (by default) both the code and the printed value of the expression will be inserted into the manual page.

#' ```{r}
#' # This block of code will be evaluated
#' summary(iris)
#' ```

Code blocks support knitr chunk options, e.g. to keep the output of several expressions together, you can specify results= "hold":

#' ```{r results = "hold"}
#' names(mtcars)
#' nrow(mtcars)
#' ```

By default plots create .png files in the man/figures directory. The file names are created from the chunk names:

#' ```{r r-cookbook-barplot}
#' # https://r-graphics.org/recipe-distribution-basic-hist
#' library(ggplot2)
#' ggplot(faithful, aes(x = waiting)) +
#'   geom_histogram()
#' ```

Both the inline R code and the markdown code fences are evaluated when you run devtools::document() (or roxygenize()). You probably want to avoid lengthy computations, or set up caching to keep your package development workflow snappy.

Please see vignette("rd-formatting") for more about dynamic documentation, including potential caveats.

Line ending conversion

This version of roxygen2 does a much better job at keeping the line ending characters consistent within each file, across operating systems. In particular, if a generated file has only Windows (CR LF) line endings, roxygen2 keeps the file that way. If a file has mixed Windows and Unix (LF) line endings, roxygen2 converts all line endings to Unix (LF). For new files roxygen2 uses LF file endings. If you want to convert a file from CR LF line endings to LF, simply remove it and let roxygen2 re-create it.

The new convention works better with git on Windows. Windows git, depending on configuration, might or might not convert between CR LF and LF line endings when checking out and when committing code. No matter which git option you use, roxygen2 now does not introduce spurious line ending changes.

Thanks to @jonthegeek and @jimhester for working on this feature.

Some other improvements

  • Hyperlinks to R6 methods are also added in the PDF manual.

  • @description NULL and @details NULL no longer fail; instead, these tags are ignored, except for @description NULL in package level documentation, where it can be used to suppress the auto-generated ‘Description’ section.

  • Multiple @format tags are now combined.

  • @evalNamespace() works again.

Acknowledgements

A big thanks to all 40 contributors who helped make this release possible! @alandipert, @allenzhuaz, @BenEngbers, @bgctw, @billdenney, @Bisaloo, @cboettig, @dmurdoch, @dragosmg, @eddelbuettel, @gaborcsardi, @genomaths, @goldingn, @hadley, @HenrikBengtsson, @Hong-Revo, @hughjonesd, @iferres, @IndrajeetPatil, @jameslamb, @jimhester, @kingaa, @kortschak, @krlmlr, @maelle, @michaelquinn32, @mikemahoney218, @mstr3336, @muschellij2, @nteetor, @ntguardian, @pat-s, @RaphaelS1, @russHyde, @s-fleck, @stefanfritsch, @strboul, @TomKellyGenetics, @VPetukhov, and @zachary-foster.

Contents