This vignette introduces the
basics of roxygen2 for documenting functions. See
vignette("rd-other") for documenting other types of objects
and vignette("reuse") for reusing documentation across
topics.
A roxygen block is a sequence of lines starting with
#' (optionally preceded by white space).
The first lines of the block is called the introduction and forms the title, description, and details, as described below. The introduction continues until the first tag.
Tags start with @, like @details or
@param. Tags must appear at the beginning of a line and
their content extends to the start of the next tag or the end of the
block. Text within the description or tags can be formatted using
Markdown or Rd commands; see
vignette("rd-formatting") for details.
A block ends when it hits R code, usually a function or object
assignment. Blocks ignore empty lines, including lines made up of
non-roxygen comments. If you need to separate two blocks, use
NULL.
If you want to use roxygen2 documentation tags without generating an
.Rd file, you can use @noRd to suppress file
generation for a given topic. This is useful if you want to use roxygen2
conventions for documenting an internal function; only people reading
the source doc will be able to read the docs.
Each documentation block starts with some text which defines the
title, the description, and the details. Here’s an example showing what
the documentation for sum() might look like if it had been
written with roxygen:
#' Sum of vector elements
#'
#' `sum` returns the sum of all the values present in its arguments.
#'
#' This is a generic function: methods can be defined for it directly
#' or via the [Summary()] group generic. For this to work properly,
#' the arguments `...` should be unnamed, and dispatch is on the
#' first argument.
sum <- function(..., na.rm = TRUE) {}This introductory block is broken up as follows:
The first sentence is the title: that’s what you
see when you look at help(package = mypackage) and is shown
at the top of each help file. It should generally fit on one line, be
written in sentence case, and not end in a full stop.
The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does.
The third and subsequent paragraphs go into the details: this is a (often long) section that comes after the argument description and should provide any other important details of how the function operates. The details are optional.
You can also use explicit @title,
@description, and @details tags. This is
unnecessary unless you want to have a multi-paragraph description,
bulleted list, or other more exotic structure.
#' Sum of vector elements
#'
#' @description
#' `sum` returns the sum of all the values present in its arguments.
#'
#' @details
#' This is a generic function: methods can be defined for it directly
#' or via the [Summary()] group generic. For this to work properly,
#' the arguments `...` should be unnamed, and dispatch is on the
#' first argument.Functions are the most commonly documented objects. Functions require
three tags: @param, @returns, and
@examples.
Use @param name description to describe each input to
the function. The description should provide a succinct summary of
parameter type (e.g. a string, a numeric vector), and if not obvious
from the name, what the parameter does. The description is a sentence so
should start with a capital letter and end with a full stop. It can span
multiple lines (or even paragraphs) if necessary. All parameters must be
documented.
If two or more arguments are tightly coupled, you can document them
in one place by separating the names with commas (no spaces). For
example, to document both x and y, you can say
@param x,y Numeric vectors.
@returns description describes the output from the
function. Briefly describe the type/shape of the output, not the
details.
All functions must have a documented return value for initial CRAN submission.
@examples provides executable R code showing how to use
the function in practice. This is a very important part of the
documentation because many people look at the examples before reading
anything. Example code must work without errors as it is run
automatically as part of R CMD check.
For the purpose of illustration, it’s often useful to include code
that causes an error. You can do this by wrapping the code in
try() or using \dontrun{} to exclude from the
executed example code.
For finer control, you can use @examplesIf:
This generates
\examples{
\dontshow{if (interactive() (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
gh_organizations(since = 42)
\dontshow{\}) # examplesIf}
}This way, the code evaluating whether the example can be run is not shown to users reading the help, but it still prevents R CMD check failures.
Instead of including examples directly in the documentation, you can
put them in separate files and use
@example path/relative/to/package/root to insert them into
the documentation.
All functions must have examples for initial CRAN submission.
In most case, the function usage (which appears beneath the
description in the generates docs) will be automatically derived from
the function specification. For the cases where it is not, please file an issue and
use @usage to override the default with what you want. If
you want to suppress the usage altogether (which is sometimes useful for
internal or deprecated functions), you can use
@usage NULL.