Convert Rd to 'Roxygen' Documentation

Functions to convert Rd to 'roxygen' documentation. It can parse an Rd file to a list, create the 'roxygen' documentation and update the original R script (e.g. the one containing the definition of the function) accordingly. This package also provides utilities that can help developers build packages using 'roxygen' more easily. The 'formatR' package can be used to reformat the R code in the examples sections so that the code will be more readable.

Convert Rd to roxygen documentation. For more information, see


      CHANGES IN Rd2roxygen VERSION 1.6.1


o existing tarballs of the source package will be deleted before building the new tarball with rab()

      CHANGES IN Rd2roxygen VERSION 1.6


o rab(install = TRUE) can automatically generate an Rd file for objects that are imported from other packages and later re-exported in the current package; this is done through the internal function importRd()

o when build = FALSE and install = TRUE in rab(), the package directory instead of the built tar ball is installed

o added an argument install.opts to rab() to specify options for R CMD INSTALL (default: --with-keep.source if build = FALSE, otherwise empty)

o added an argument before to rab() so we can evaluate an R expression before the package is roxygenized and built

o if the Examples section starts with a special token # !formatR, the example code will not be reformatted

o spaces will be added after commas in \item{}, e.g. \item{x,y,z}{} will be converted to \item{x, y, z}{}

      CHANGES IN Rd2roxygen VERSION 1.5


o make sure the correct R executable is used (i.e. always use file.path(R.home('bin'), 'R'))

      CHANGES IN Rd2roxygen VERSION 1.4


o added a new argument 'build.opts' to rab() to pass options to R CMD build


o the new feature @returnItem introduced in Rd2roxygen 1.1 was temporarily removed, since it is not supported in roxygen2 (3.0.0) yet

      CHANGES IN Rd2roxygen VERSION 1.3


o Rd2roxygen depends on formatR v0.9 for better handling of example and usage code

      CHANGES IN Rd2roxygen VERSION 1.2


o added NULL to create_roxygen() when docType is data or package (#9)

o Rd2roxygen() tries to add the @export tags according to the exported names in the NAMESPACE (#10, #11 and #12)

o when reformatting usage and example sections, rab() tries to make code width smaller than 90, as required by R CMD check


o the package vignette is built with knitr alone now (under R 3.0.x)

      CHANGES IN Rd2roxygen VERSION 1.1


o \item{} in the \value{} section will be formatted as the @returnItem tag, which is a new tag in roxygen2 (> 2.2.2) (#8) (thanks, Andreas Alfons)

o R code in \dontrun{}, \dontshow{} and \donttest{} can be reformatted by formatR now


o the vignette is built with knitr via the Makefile; in previous versions, it was a fake Rnw document (essentially a weaved tex file)

o dependency on roxygen2 and formatR was changed to Imports

o default value for 'check.opts' in rab() is '--as-cran' now

      CHANGES IN Rd2roxygen VERSION 1.0-7


o @section is supported now: \section{title}{content} will be converted to ##' @section title: content (thanks, Brian G. Peterson)


o the package vignette now compiles with knitr instead of Sweave

      CHANGES IN Rd2roxygen VERSION 1.0-6


o \dontrun{} can be correctly reformatted now; there was a bug in the previous version when options(replace.assign = TRUE)

      CHANGES IN Rd2roxygen VERSION 1.0-5


o usage for S3 methods like \method{generic}{class}(param = value) can be correctly reformatted now; in previous versions rab() will ignore such usage sections

      CHANGES IN Rd2roxygen VERSION 1.0-4


o Rd files that have \docType{data} or \docType{package} (for datasets and package documentation) are written into xxx-package.R directly; these names are not looked up in R scripts under the R directory of the source package

o Rd comments (following %) will be ignored when generating roxygen comments for arguments

      CHANGES IN Rd2roxygen VERSION 1.0-3


o a complete example of running Rd2roxygen() on a real package was added to ?Rd2roxygen

o re-run Rd2roxygen() on a package will remove the roxygen comments in R scripts before adding new roxygen comments parsed from Rd files; in old versions of this package, the old roxygen comments were not removed, hence the comments were added incrementally above the function objects, which was certainly not desirable


o all these forms of quotes in assignments are allowed in Rd2roxygen(): foo <-, 'foo' <-, "foo" <-, and = can be used as the assigning operator as well

      CHANGES IN Rd2roxygen VERSION 1.0-2


o the usage sections in Rd files will be reformatted by default again when calling rab() (this feature was formerly removed in version 1.0-0)


o rab(..., install = TRUE) will install the *.tar.gz file rather than the package directory; similarly, rab(..., check = TRUE) checks the tar ball as well

      CHANGES IN Rd2roxygen VERSION 1.0-1


o the percent symbols in the examples code will be unescaped (i.e. % becomes %) before the code is reformatted, then escaped again; this can avoid errors when reformatting the code, since % is an illegal character in R

      CHANGES IN Rd2roxygen VERSION 1.0-0


o Rd2roxygen uses the brand-new roxygen2 rather than the old

roxygen package which is no longer maintained; users are recommended to read the NEWS file of roxygen2 carefully. Some major changes include: the description is in the second paragraph rather than the second line now (i.e. there is an empty line between the title and description); @format and @source are supported, and a series of new tags are introduced in roxygen2 too


o the escape and use.Rd2 arguments are removed in rab() since

roxygen2 can handle these cases elegantly

o roxygen.dir is the same as the package directory by default, so

rab() will write all the documentations in the original package directory

o the usage section is no longer reformatted by formatR; roxygen2

formats it nicely

o the function rm_undocumented() is no longer needed, so it was

removed from this package; use @noRd if you do not want the documentation of a certain object to be generated by roxygen2

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.6.2 by Yihui Xie, 2 months ago

Report a bug at

Browse source code at

Authors: Hadley Wickham [aut], Yihui Xie [aut, cre]

Documentation:   PDF Manual  

GPL license

Imports roxygen2, formatR

Suggests knitr, rmarkdown

See at CRAN