In-Line Documentation for R

Generate your Rd documentation, 'NAMESPACE' file, and collation field using specially formatted comments. Writing documentation in-line with code makes it easier to keep your documentation up-to-date as your requirements change. 'Roxygen2' is inspired by the 'Doxygen' system for C++.

--Homer, 7th century BCE

Why use roxygen2?

The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in the man/ directory. Here's a simple example from the stringr package:

#' The length of a string (in characters).
#' @param string input character vector
#' @return numeric vector giving number of characters in each element of the
#'   character vector.  Missing strings have missing length.
#' @seealso \code{\link{nchar}} which this function wraps
#' @export
#' @examples
#' str_length(letters)
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
  string <- check_string(string)
  nc <- nchar(string, allowNA = TRUE) <-

When you roxygenise() (or devtools::document()) your package these comments will be automatically transformed to the Rd file you need to pass R CMD check:

\title{The length of a string (in characters).}
  \item{string}{input character vector}
The length of a string (in characters).
\seealso{\code{\link{nchar}} which this function wraps}
  numeric vector giving number of characters in each element of the
  character vector.  Missings string have missing length.
str_length(c("i", "like", "programming", NA))


To get the current released version from CRAN:


To get the current development version from github:

# install.packages("devtools")


Roxygen does a live analysis of your source code: it loads all the code in your package, so it can create documentation using values in an R environment, not just source code. However, simulating package loading is rather tricky to do in general, so there are two ways to do it with roxygen:

  • roxygen2::roxygenise() just sources all files in the R/ directory

  • devtools::document() sources all files in the R/ directory, compiles source code in the src/ directory, loads data in the data/ directory and generally does an accurate job of simulating package loading.

If you have a simple package, you can use roxygenise(), but for anything more complicated, I recommend that you use document().


roxygen2 comes with four roclets, tools for parsing your source code and producing files useful for documenting your package:

  • collate_roclet: allows you to add @include directives to ensure that files are loaded in the order they are needed

  • namespace_roclet: creates your NAMESPACE automatically. 95% of the time all you need to do is label functions, methods and classes that you want to export with the @export tag

  • rd_roclet: produces Rd files by inspecting both function definitions and roxygen2 comments in the source code

  • vignette_roclet: builds vignettes using tools::buildVignette().

By default, roxygenise will run the first three, but you can choose which ones to run using the roclet parameter, or field Roxygen in your DESCRIPTION:

Roxygen: list(roclets = c("rd", "collate"))

  • Hail, Hephaistos! Grant skill and weal.


Reference manual

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


6.0.1 by Hadley Wickham, a year ago

Report a bug at

Browse source code at

Authors: Hadley Wickham [aut, cre, cph], Peter Danenberg [aut, cph], Manuel Eugster [aut, cph], RStudio [cph]

Documentation:   PDF Manual  

GPL (>= 2) license

Imports stringr, stringi, brew, digest, methods, Rcpp, R6, desc, commonmark, xml2, utils

Suggests testthat, knitr, devtools, rmarkdown, covr

Linking to Rcpp

Imported by Rd2roxygen, aoos, civis, docstring, document, exampletestr, redland, uavRmp, wtss.

Depended on by miscFuncs, sqlutils.

Suggested by BAS, BayesianTools, CorShrink, DescribeDisplay, DrImpute, FedData, GGally, GSODR, Grid2Polygons, JuniperKernel, OpenMx, PP, PPforest, Quandl, R4CouchDB, RItools, RSocrata, RcppProgress, Rilostat, SimRVPedigree, TimeProjection, WufooR, aRxiv, analogsea, ashr, autovarCore, bikedata, binomen, bold, broman, bunchr, camsRad, ccafs, charlatan, chromer, covmat, crminer, datadr, deisotoper, devtools, df2json, discreteRV, dodgr, dotCall64, dynr, earlyR, ecd, edgarWebR, elastic, enigma, epitrix, etseed, eurostat, fakemake, flippant, gapfill, geometa, geoops, geosapi, geozoo, getCRUCLdata, getlandsat, ggenealogy, gistr, gitlabr, googleAuthR, gqlr, h5, hoardr, httping, icd, ifaTools, iheatmapr, intergraph, isdparser, jaod, jiebaR, jqr, knitrBootstrap, lawn, ldhmm, learnrbook, lineup, mgarchBEKK, micompr, mizer, mregions, mtconnectR, multipanelfigure, nat.utils, natserv, nima, nlmeU, nneo, nscancor, nsprcomp, oai, odr, openadds, optmatch, originr, osmdata, osmplotr, paleobioDB, pcIRT, photobiology, pleiades, pmap, pnn, popEpi, prioritizr, projections, protoclass, pwrRasch, qtlcharts, questionr, rAvis, rClinicalCodes, rMouse, rYoutheria, ragtop, randgeo, rappdirs, raptr, rbgm, rbhl, rbison, rbokeh, rbundler, rcoreoa, rcrossref, rdatacite, rddapp, rdpla, recexcavAAR, refimpact, rerddap, rex, rgbif, rif, ritis, rnoaa, roadoi, rorcid, rpcdsearch, rpf, rredlist, rsdmx, rsnps, rstanarm, rtimes, rvertnet, scholar, sdmvspecies, seaaroundus, sinew, solr, solrium, sotkanet, spdynmod, spocc, taxa, taxize, taxizedb, tcR, tcpl, traits, trelliscope, urlshorteneR, vdiffr, vortexR, webmockr, wikitaxa, worrms, wrswoR, xoi.

See at CRAN