roxygen2-documentation

name	roxygen2 Documentation
description	Complete guide to roxygen2 tags, Markdown support, cross-references, and documentation patterns for functions, data, and packages

roxygen2 Documentation

Overview

roxygen2 allows you to write documentation directly above your R code using special comments starting with #'. This skill covers all essential roxygen2 tags, Markdown formatting, and documentation patterns.

Core Concepts

Basic Structure

#' Function title (one line, sentence case)
#'
#' Longer description paragraph providing more details about what
#' the function does, when to use it, and any important context.
#'
#' @param x Description of parameter x
#' @param y Description of parameter y
#' @returns Description of return value
#' @export
#' @examples
#' my_function(1, 2)

my_function <- function(x, y) {
  # implementation
}

Required components:

1. Title (first line, no blank line before it)
2. Blank line (separates title from description)
3. Description (optional but recommended)
4. Blank line (separates description from tags)
5. Tags (@param, @returns, @export, etc.)

Generating Documentation

# Generate .Rd files and NAMESPACE:
devtools::document()

# Or:
roxygen2::roxygenise()

# Preview documentation:
?my_function

Essential Tags

@param

Documents function parameters. One @param per parameter.

#' @param x A numeric vector of values
#' @param y A numeric vector, same length as x
#' @param method Character string specifying the method to use.
#'   Options are "mean" (default), "median", or "mode".
#' @param verbose Logical. If TRUE, prints progress messages.
#'   Default is FALSE.
#' @param ... Additional arguments passed to underlying functions

Patterns:

• Start with type description ("A numeric vector", "Character string")
• Explain constraints (length, range, allowed values)
• Document defaults if not obvious
• Use ... for dots

@returns (Preferred) / @return

Documents what the function returns. Use @returns (plural) in new code.

#' @returns A numeric vector of the same length as the input
my_function <- function(x) {
  x * 2
}

#' @returns A data frame with columns:
#'   \describe{
#'     \item{id}{Character. Unique identifier}
#'     \item{value}{Numeric. Measured value}
#'     \item{timestamp}{POSIXct. Time of measurement}
#'   }
my_summarize <- function(data) {
  # ...
}

#' @returns Invisible NULL. Called for side effects (prints plot).
my_plot <- function(x) {
  plot(x)
  invisible(NULL)
}

#' @returns A list with components:
#'   * `estimate`: Numeric vector of estimates
#'   * `std_error`: Standard errors
#'   * `p_value`: P-values
my_test <- function(x, y) {
  list(
    estimate = c(1, 2),
    std_error = c(0.1, 0.2),
    p_value = c(0.01, 0.05)
  )
}

Note: @return (singular) is older but still works. @returns is now preferred.

@export

Marks function for export (makes it available to users).

#' User-facing function
#' @export
public_function <- function() {
  # ...
}

#' Internal function (no @export)
internal_helper <- function() {
  # ...
}

When to export:

• Functions users should call directly
• S3 methods for generics from other packages (often)
• Datasets (automatically exported from data/)

When NOT to export:

• Internal helper functions
• Functions only called by other package functions
• S3 methods for your own generics (use @export with method)

@examples

Provides executable examples.

#' @examples
#' # Basic usage
#' result <- my_function(1:10)
#'
#' # With different parameters
#' result2 <- my_function(1:10, method = "median")
#'
#' # Handling edge cases
#' my_function(numeric(0))  # Empty input

my_function <- function(x, method = "mean") {
  # ...
}

Best practices:

• Include comments explaining what each example shows
• Show basic usage first, then advanced
• Demonstrate important edge cases
• Keep examples short and focused
• Examples are run by R CMD check!

@examplesIf

Conditionally run examples (new in roxygen2 7.2.0).

#' @examplesIf requireNamespace("ggplot2", quietly = TRUE)
#' library(ggplot2)
#' ggplot(data, aes(x, y)) + geom_point()


#' @examplesIf interactive()
#' # Only run in interactive sessions
#' my_interactive_function()


#' @examplesIf identical(Sys.getenv("NOT_CRAN"), "true")
#' # Only on GitHub Actions, not CRAN
#' slow_test()

\dontrun{} vs \donttest{}

Control example execution during R CMD check.

#' @examples
#' # This runs:
#' my_function(1:10)
#'
#' \dontrun{
#' # This is shown but NEVER run (not even by check):
#' # Use for code that requires user interaction or credentials
#' my_function(get_user_input())
#' set_api_key("your-key-here")
#' }
#'
#' \donttest{
#' # This is run by check, but not by example():
#' # Use for slow operations
#' very_slow_operation()
#' }

Guidelines:

• Prefer runnable examples when possible
• Use \dontrun{} for interactive code, credentials, web APIs
• Use \donttest{} for slow operations (>5 seconds)
• Use @examplesIf instead when appropriate

@importFrom

Imports specific functions from other packages into your namespace.

#' @importFrom dplyr filter mutate select
#' @importFrom rlang .data %||%
#' @importFrom stats median sd
NULL

Placement:

• Package-level documentation file (R/mypackage-package.R)
• Or in individual function documentation
• Or in a dedicated R/aaa-imports.R file

# R/aaa-imports.R
#' @importFrom dplyr filter mutate select arrange
#' @importFrom rlang .data .env %||% !! !!!
#' @importFrom magrittr %>%
NULL

@import

Imports entire package namespace (rarely recommended).

#' @import rlang
NULL

Only use for:

• rlang (if building tidyverse-style package)
• Your own internal utilities package

Avoid for:

• Most packages (use @importFrom or pkg::fun() instead)
• Risk of namespace conflicts

@keywords internal

Marks function as internal (hides from package index).

#' Internal helper function
#'
#' This function is not intended for direct use.
#'
#' @keywords internal
#' @export
internal_but_exported <- function() {
  # Sometimes needed for S3 methods, package architecture
}

Use when:

• Function must be exported (e.g., S3 method) but isn't user-facing
• Internal APIs for advanced users

Inheritance and Linking

@inheritParams

Inherits parameter documentation from another function.

#' Base function
#' @param x A numeric vector
#' @param y A numeric vector
#' @param method Method to use: "mean", "median", or "mode"
base_function <- function(x, y, method = "mean") {
  # ...
}

#' Wrapper function
#' @inheritParams base_function
#' @param z Additional parameter
wrapper_function <- function(x, y, method = "mean", z) {
  base_function(x, y, method)
  # ... use z ...
}

Benefits:

• Reduces duplication
• Ensures consistency
• Easier maintenance

@inherit

Inherits various documentation sections.

#' Original function
#' @param x Input
#' @returns Output
#' @examples
#' original(1:10)

original <- function(x) {
  # ...
}

#' @inherit original examples
#' @inheritParams original
#' @returns Modified output
modified <- function(x) {
  # different implementation
}

Can inherit:

• @inherit fun params - all parameters
• @inherit fun return - return value
• @inherit fun examples - examples
• @inherit fun description - description
• @inherit fun details - details
• @inherit fun - everything

@family

Creates "See Also" links to related functions.

#' @family statistical functions
mean_wrapper <- function(x) {
  mean(x)
}

#' @family statistical functions
median_wrapper <- function(x) {
  median(x)
}

#' @family statistical functions
mode_wrapper <- function(x) {
  # ...
}

Generates links: "Other statistical functions: median_wrapper(), mode_wrapper()"

@seealso

Manual cross-references and external links.

#' @seealso [related_function()] for related functionality
#' @seealso [other_package::their_function()] for alternative approach
#' @seealso <https://example.com> for more details
#' @seealso `vignette("introduction")` for tutorial

@rdname

Combines documentation of multiple functions on one page.

#' Get or set configuration
#'
#' @param key Configuration key
#' @param value Configuration value
#' @rdname config
#' @export
get_config <- function(key) {
  pkg_env$config[[key]]
}

#' @rdname config
#' @export
set_config <- function(key, value) {
  pkg_env$config[[key]] <- value
  invisible(value)
}

Generates single help page: ?config shows both functions.

Use for:

• Getter/setter pairs
• Function families that are always used together
• Different interfaces to same functionality

@describeIn

Documents multiple related items with individual descriptions.

#' Process data
#'
#' @param x Input data
#' @export
process <- function(x) {
  UseMethod("process")
}

#' @describeIn process Process numeric vectors
#' @export
process.numeric <- function(x) {
  # ...
}

#' @describeIn process Process character vectors
#' @export
process.character <- function(x) {
  # ...
}

#' @describeIn process Process data frames
#' @export
process.data.frame <- function(x) {
  # ...
}

Generates: Single page with subsections for each method.

Markdown Support

Enable in DESCRIPTION:

Roxygen: list(markdown = TRUE)

Text Formatting

#' Function with *italic*, **bold**, and `code` text
#'
#' You can use _italic_ and __bold__ alternatives too.
#'
#' Inline code: `x + y`
#'
#' Code blocks:
#' ```
#' result <- my_function(
#'   x = 1:10,
#'   method = "mean"
#' )
#' ```

Lists

#' Bulleted list:
#' * Item 1
#' * Item 2
#'   * Nested item
#' * Item 3
#'
#' Numbered list:
#' 1. First step
#' 2. Second step
#' 3. Third step
#'
#' Definition list:
#' * `term1`: Definition of term 1
#' * `term2`: Definition of term 2

Links

#' See [my_function()] for details
#'
#' See [other_package::their_function()] for alternatives
#'