Build Status

all' hileth', Hephaiste; didou d'areten te kai olbon.* --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 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:

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


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

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