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 automatically generate .Rd files in man/, NAMESPACE, and, if needed, the Collate field in DESCRIPTION.

This version of roxygen2 is a fork of the original which fixes some issues and supports recursive inheritance of dot parameters, allowing for more detailed information about parameters that can be passed through to underlying functions.

It can be used by specifying this repository in the description file with the following:

...
RoxygenNote: 7.3.2.9004
Config/Needs/build: robchallen/roxygen2
...

And adding into the .github/pkgdown.yaml generated by usethis::use_pkgdown_github_pages()

...
      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::pkgdown, any::devtools, local::.
          needs: website, build
      
      - name: Run Roxygen2
        run: devtools::document
        shell: Rscript {0}
      
      - name: Build site
...

this will ensure that the patched roxygen2 is available during pkgdown site build and the documentation is generated using it. However this declaration only affects documentation build by GitHub runners (and possibly r-universe), and hence the website version of the documentation.

Installation

# Install this patched version of roxygen2 from GitHub:
# install.packages("pak")
pak::pak("robchallen/roxygen2")

Usage

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 the man/ directory. Here's a simple 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 you roxygenise() (or devtools::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.

Learn more

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

• Start with vignette("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 a NAMESPACE file, how namespacing works in R, and how you can use roxygen2 to be specific about what your package needs and supplies.

• For the Collate field in the DESCRIPTION, see ?update_collate().