roxygen2

roxygen2 automates the generation of R documentation. Instead of manually writing .Rd files, you write descriptive comments directly above your function definitions in your source code.

When you run the documentation process, roxygen2 parses these comments and automatically generates:

• .Rd files in the man/ directory
• A NAMESPACE file
• The Collate field in the DESCRIPTION file (if required)

To transform your source code comments into formal R documentation, call roxygenise() or use devtools::document(). This will process your package and populate the man/ directory with the necessary .Rd files.

# After writing documentation comments in your R files:
roxygenise()
# OR
devtools::document()

You can install the stable version of roxygen2 from CRAN using install.packages(). If you need the development version, use pak::pak() to install directly from GitHub.

# Install roxygen2 from CRAN
install.packages("roxygen2")

# Or the development version from GitHub:
# install.packages("pak")
pak::pak("r-lib/roxygen2")

If you encounter a test failure stating ✖ Package [package_name] does not use roxygen2 when using functions like usethis::use_pipe(), it indicates that the package environment is not correctly configured for roxygen2 documentation.

To resolve this, run devtools::document() once to generate the necessary documentation files and ensure the package is recognized as using roxygen2.

# Run this to initialize roxygen2 documentation
devtools::document()

If a test fails with the error Error: d[1, "Config/roxygen2/version"] == "8.0.0" is not TRUE, it means the package's DESCRIPTION file does not have the expected Config/roxygen2/version field set to the required version.

This error typically occurs during automated checks (like revdepcheck) when a package is expected to be compatible with a specific version of roxygen2 (in this case, 8.0.0) but the metadata in the DESCRIPTION file does not match.

Use special comment tags (starting with @) to define documentation elements. Common tags include @param, @return, @export, and @examples. The @export tag is critical for making a function available to users of your package.

Example of documenting a function:

#' The length of a string
#'
#' Technically this returns the number of "code points", in a string. One
#' code point usually corresponds to one character, but not always.
#'
#' @inheritParams str_detect
#' @return A numeric vector giving number of characters (code points) in each
#'    element of the character vector. Missing string have missing length.
#' @seealso [stringi::stri_length()] which this function wraps.
#' @export
#' @examples
#' str_length(letters)
#' str_length(NA)
#' str_length(factor("abc"))
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
}