16.1 roxygen2 basics

16.1.1 Documentation workflow

Four main steps:

1. Opening move is add roxygen comments above your functions in your R/.R files
2. Run devtools::document()
3. Preview documentation with ?function
4. Rinse and repeat

16.1.2 roxygen2 comments, blocks, and tags

• Four basic building blocks:

  1. #' - roxygen comment
  2. Multiple # lines - a block
     • Wrapped at 80 characters (Ctrl/Cmd + Shift + / or reflow comment)
  3. Tags - Breaks up the blocks
     • @tagName details
  4. Introduction
     • First sentence is the title
     • Second paragraph is the description (what does the function do?)
     • Paragraphs >= 3 allow for more detail

• All objects must have a title and description

• Details are optional

• Blocks and tags give documentation structure

Here’s a simple first example: the documentation for str_unique().

#' Remove duplicated strings
#'
#' `str_unique()` removes duplicated values, with optional control over
#' how duplication is measured.
#'
#' @param string Input vector. Either a character vector, or something
#'  coercible to one.
#' @param ... Other options used to control matching behavior between duplicate
#'   strings. Passed on to [stringi::stri_opts_collator()].
#' @returns A character vector, usually shorter than `string`.
#' @seealso [unique()], [stringi::stri_unique()] which this function wraps.
#' @examples
#' str_unique(c("a", "b", "c", "b", "a"))
#'
#' # Use ... to pass additional arguments to stri_unique()
#' str_unique(c("motley", "mötley", "pinguino", "pingüino"))
#' str_unique(c("motley", "mötley", "pinguino", "pingüino"), strength = 1)
#' @export
str_unique <- function(string, ...) {
  ...
}

16.1.3 Key markdown features

1. Backticks for inline code

#' I like `thisfunction()`, because it's great.

2. Square brackets for auto-linked function

#' It's obvious that `thisfunction()` is better than [otherpkg::otherfunction()]
#' or even our own [olderfunction()].

3. Vignettes

• vignette("rd-formatting", package = "roxygen2")

• vignette("reuse", package = "roxygen2")

• vignette("linking", package = "pkgdown")

4. Lists

#' Best features of `thisfunction()`:
#' * Smells nice
#' * Has good vibes