Repository files navigation

The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to automatically generate.Rd files inman/,NAMESPACE, and, if needed, theCollate field inDESCRIPTION.

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

The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in theman/ directory. Here's asimple example from the stringr package:

#' 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. For example,#' an u with a umlaut might be represented as a single character or as the#' combination a u and an umlaut.#'#' @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) {}

When youroxygenise() (ordevtools::document()) your package these comments will be automatically transformed to the.Rd that R uses to generate the documentation you see when you type?str_length.

To get started, first readvignette("roxygen2"). Then read more about the specific package component that you want to generate:

• Start withvignette("rd") to learn how document your functions with roxygen2.

• vignette("rd-other") discusses how to document other things like datasets, the package itself, and the various pieces used by R's OOP systems.

• vignette("rd-formatting") gives the details of roxygen2's rmarkdown support.

• vignette("reuse") demonstrates the tools available to reuse documentation in multiple places.

• vignette("namespace") describes how to generate aNAMESPACE file, how namespacing works in R, and how you can use roxygen2 to be specific about what your package needs and supplies.

• For theCollate field in theDESCRIPTION, see?update_collate().