Write Roxygen Documentation

Create complete roxygen2 documentation for R package functions, datasets, and classes.

When to Use

• •Adding documentation to a new exported function
• •Documenting internal helper functions
• •Documenting package datasets
• •Documenting S3/S4/R6 classes and methods
• •Fixing documentation-related R CMD check notes

Inputs

• •Required: R function, dataset, or class to document
• •Optional: Related functions for cross-referencing (@family, @seealso)
• •Optional: Whether the function should be exported

Procedure

Step 1: Write Function Documentation

Place roxygen comments directly above the function:

#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
  # implementation
}

Expected: Complete documentation with all required tags.

Step 2: Essential Tags Reference

Step 3: Document Datasets

Create R/data.R:

#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#'   \item{date}{Date of observation}
#'   \item{city}{City name}
#'   \item{temp_c}{Temperature in Celsius}
#'   \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"

Step 4: Document the Package

Create R/packagename-package.R:

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

Step 5: Handle Special Cases

Functions with dots in names (S3 methods):

#' @export
#' @rdname process
process.myclass <- function(x, ...) {
  # S3 method
}

Reusing documentation with @inheritParams:

#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
  # implementation
}

No visible binding fix using .data pronoun:

#' @importFrom rlang .data
my_function <- function(df) {
  dplyr::filter(df, .data$column > 5)
}

Step 6: Generate Documentation

devtools::document()

Expected: man/ directory updated, NAMESPACE regenerated.

On failure: Check for roxygen syntax errors. Common: unclosed brackets in \describe{}, missing #' prefix.

Validation

• • Every exported function has @param, @return, and @examples
• • devtools::document() runs without errors
• • devtools::check() shows no documentation warnings
• • @family tags group related functions correctly
• • Examples run without errors (test with devtools::run_examples())

Common Pitfalls

• •Missing @return: CRAN requires all exported functions to document their return value
• •Examples that need internet/auth: Wrap in \dontrun{} with a comment explaining why
• •Slow examples: Use \donttest{} for examples that work but take too long for CRAN
• •Markdown in roxygen: Enable with Roxygen: list(markdown = TRUE) in DESCRIPTION
• •Forgetting to run devtools::document(): Man pages are generated, not hand-written

Related Skills

• •create-r-package - initial package setup including roxygen configuration
• •write-testthat-tests - test the functions you document
• •write-vignette - long-form documentation beyond function reference
• •submit-to-cran - documentation requirements for CRAN