Roxygen Quick Reference

roxygen2 is an R package that allows you to write in-source documentation for your package functions and objects.

Write documentation above your package functions with the #' comment prefix.

Documenting Functions

Example

#' This is the title.
#'
#' This is the description.
#'
#' These are further details.
#'
#' @section A Custom Section:
#'
#' Text accompanying the custom section.
#'
#' @param x A description of the parameter 'x'. The
#'   description can span multiple lines.
#' @param y A description of the parameter 'y'.
#'
#' @export
#'
#' @examples
#' add_numbers(1, 2) ## returns 3
#'
#' ## don't run this in calls to 'example(add_numbers)'
#' \dontrun{
#'    add_numbers(2, 3)
#' }
#'
#' ## don't test this during 'R CMD check'
#' \donttest{
#'    add_numbers(4, 5)
#' }
add_numbers <- function(x, y) {
     x + y
}

Common Tags

@param <name> <description> Document a function parameter.
@export Make this function available to users of your package.
@examples <r-code>

Inline R code showing how the function is used.

Wrap code blocks in \dontrun{} to prevent them from running on calls to example(). Use \donttest{} to disable running this code in R CMD check.

@return Describe what this function returns.
@family <family-name> Automatically generate links to other functions within this family in the documentation's See Also section.
@seealso Provide links to other resources that could help users understand how to use your function.
@inheritParams <function>

Re-use parameter documentation from another function.

Use @inheritParams <package::function> to re-use documentation from a function in a separate package.

@section <name>:

Provide a custom section with the name <name>. The line must end with a colon (:).

In addition, you can use @keywords internal to ensure that documentation for a particular function is generated, but not added to the package index.

Documenting Packages

By convention, package documentation is usually included in a file R/<package-name>-package.R. The roxygen block providing package documentation should contain the @docType package field declaration, and should end with NULL.

Example

#' Package Name
#'
#' Package description.
#'
#' @docType package
#' @name <package-name>
#' @import assertthat
#' @importFrom utils head tail
#' @useDynLib <package-name>
NULL

Common Tags

@import <pkg> Import all symbols from a package, for use in your own package's functions.
@importFrom <pkg> <symbols...> Selectively import symbols from a package, for use in your own package's functions.
@useDynLib <own-pkg> Include this if your package contains C / C++ code.

Rd Markup

Use R Documentation LaTeX-style markup to further style your documentation.

\emph{} For italicized text.
\strong{} For bold text.
\code{} For code or otherwise pre-formatted text.
\link{object}

\link[=class]{object}
\linkS4class{S4Class}

Used to link to other R documentation.

For example, use \code{\link{rnorm}} to link to the documentation associated with the rnorm function.

\url{URL}
\href{URL}{text}

Link to content on the internet; for example, external documentation.

Use \href{URL}{text} if you want the displayed text to differ from the linked URL.

\enumerate{<items...>}
\itemize{<items...>}
\describe{<items...>}

Provide a list of items. \enumerate{} delimits entries with sequential numbers, while \itemize{} delimits entries with bullets. 

\enumerate{
   \item Item 1.
   \item Item 2.
   \item Item 3.
}

\describe{} differs in that items are specified with labels as well as text, e.g. 

\describe{
   \item{label-1}{text-1}
   \item{label-2}{text-2}
}
\tabular{alignment}{text}

Provide a table of text.

Separate fields with \tab, and rows with \cr. alignment is a string of l / c / r, indicating left, center, and right alignment respectively. There should be one letter for each column in the table. 

\tabular{rl}{
   Entry 1 \tab Entry 2 \cr
   Entry 3 \tab Entry 4 \cr
}

Learning More

Read Hadley Wickham's guide in R Packages to learn more about how to use roxygen2 and devtools to produce documentation for your R packages.

Read the roxygen vignettes: start with the introductory vignette with vignette("roxygen2"), and view other available vignettes with vignette(package = "roxygen2").

Read R-exts for a comprehensive guide to .Rd documentation and the set of available tags (which are understood by roxygen as well).