Get started with roxygen2

Documentation is one of the most important aspects of good code. Without it, users won’t know how to use your package, and are unlikely to do so. Documentation is also useful for you in the future (so you remember what the heck you were thinking!), and for other developers working on your package. The goal of roxygen2 is to make documenting your code as easy as possible.

R provides a standard way of documenting packages: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on LaTeX. roxygen2 provides a number of advantages over writing .Rd files by hand:

As well as generating .Rd files, roxygen will also create a NAMESPACE for you, and will manage the Collate field in DESCRIPTION.

Learn more

This vignette provides a high-level description of roxygen2 and the overall workflow you’ll use with it. The other vignettes provide more detail on the most important individual components:

Running roxygen

There are three main ways to run roxygen:

You can mix handwritten Rd and roxygen2; roxygen2 will never overwrite a file it didn’t create.

Basic process

There are three steps in the transformation from roxygen comments in your source file to human readable documentation:

  1. You add roxygen comments to your source file.
  2. roxygen2::roxygenise() converts roxygen comments to .Rd files.
  3. R converts .Rd files to human readable documentation.

The process starts when you add specially formatted roxygen comments to your source file. Roxygen comments start with #' so you can continue to use regular comments for other purposes.

#' Add together two numbers
#' @param x A number.
#' @param y A number.
#' @return A number.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y

For the example above, this will generate man/add.Rd that looks like:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in ./<text>
\title{Add together two numbers}
add(x, y)
\item{x}{A number.}

\item{y}{A number.}
A number.
Add together two numbers
add(1, 1)
add(10, 1)

Rd files are a special file format loosely based on LaTeX. You can read more about the Rd format in the R extensions manual. With roxygen2, there are few reasons to know about Rd files, so here I’ll avoid discussing them as much as possible, focusing instead on what you need to know about roxygen2.

When you use ?x, help("x") or example("x") R looks for an Rd file containing \alias{x}. It then parses the file, converts it into HTML and displays it. These functions look for an Rd file in installed packages. This isn’t very useful for package development, because you want to use the .Rd files in the source package. For this reason, we recommend that you use roxygen2 in conjunction with devtools: devtools::load_all() automatically adds shims so that ? and friends will look in the development package.