7 Documentation

7.1 Introduction

Documentation of code is essential, even if the only person using your code is future-you. Use roxygen2 with markdown support enabled to keep your documentation close to the code.

7.2 Title and description

Use the first line of your function documentation to provide a concise title that describes the function, dataset, or class. Titles should use sentence case but not end with a full stop (.).

#' Combine values into a vector or list
#' 
#' This is a generic function which combines its arguments.
#'

There is no need to use the explicit @title or @description tags, except in the case of the description if it is multiple paragraphs or includes more complex formatting like a bulleted list.

#' Apply a function to each element of a vector
#'
#' @description
#' The map function transform the input, returning a vector the same length
#' as the input. 
#' 
#' * `map()` returns a list or a data frame
#' * `map_lgl()`, `map_int()`, `map_dbl()` and `map_chr()` return 
#'     vectors of the corresponding type (or die trying); 
#' * `map_dfr()` and `map_dfc()` return data frames created by row-binding 
#'    and column-binding respectively. They require dplyr to be installed.

7.3 Indents and line breaks

Always indent with one space after #'. If any description corresponding to a roxygen tag spans over multiple lines, add another two spaces of extra indention.

#' @param key The bare (unquoted) name of the column whose values will be used 
#'   as column headings.

Alternatively, tags that span over multiple lines (like @description, @examples and @section) can have the corresponding tag on its own line and then subsequent lines don’t need to be indented.

#' @examples
#' 1 + 1
#' sin(pi)

Use line breaks before/after sections where needed:

#' @section Tidy data:
#' When applied to a data frame, row names are silently dropped. To preserve,
#' convert to an explicit variable with [tibble::rownames_to_column()].
#'
#' @section Scoped filtering:
#' The three [scoped] variants ([filter_all()], [filter_if()] and
#' [filter_at()]) make it easy to apply a filtering condition to a
#' selection of variables.

7.4 Documenting parameters

For most tags, like @param, @seealso and @return, the text should be a sentence, starting with a capital letter and ending with a full stop.

#' @param key The bare (unquoted) name of the column whose values will be used 
#'   as column headings.

If some functions share parameters, you can use @inheritParams to avoid duplication of content in multiple places.

#' @inheritParams function_to_inherit_from

7.5 Capitalization and full stops

For all bullets, enumerations, argument descriptions and the like, use sentence case and put a period at the end of each text element, even if it is only a few words. However, avoid capitalization of function names or packages since R is case sensitive. Use a colon before enumerations or bulleted lists.

#' @details 
#' In the following, we present the bullets of the list:
#' * Four cats are few animals.
#' * forcats is a package.

7.6 Cross-linking

Cross-referencing is encouraged, both within R’s help file system as well as to external resources.

List closely related functions in @seealso. A single related function can be written as a sentence:

#' @seealso [fct_lump()] to automatically convert the rarest (or most common)
#'   levels to "other".

More recommendations should be organised in a bulleted list:

#' @seealso
#' * [tibble()] constructs from individual columns.
#' * [enframe()] converts a named vector into a two-column tibble (names and 
#'   values).
#' * [name-repair] documents the details of name repair.

If you have a family of related functions, you can use the @family tag to automatically add appropriate lists and interlinks to the @seealso section. Family names are plural. In dplyr, the verbs arrange(), filter(), mutate(), slice(), summarize() form the family of single table verbs.

#' @family single table verbs

When linking to external resources either include the full url inline with <>, or the surrounding prose and link text should make it extremely clear where the hyperlink goes. Avoid text like “click here”.

7.7 R code

Text that contains valid R code should be marked as such using backticks. This includes:

  • Function names, which should be followed by (), e.g. tibble().
  • Function arguments, e.g. na.rm.
  • Values, e.g. TRUE, FALSE, NA, NaN, ..., NULL
  • Literal R code, e.g. mean(x, na.rm = TRUE)
  • Class names, e.g. “a tibble will have class tbl_df …”

Do not use code font for package names. If the package name is ambiguous in the context, disambiguate with words, e.g. “the foo package”. Do not capitalize the function name if it occurs at the start of a sentence.

7.8 Internal functions

Internal functions should be documented with #' comments as per usual. Use the @noRd tag to prevent .Rd files from being generated.

#' Drop last
#'
#' Drops the last element from a vector.
#'
#' @param x A vector object to be trimmed.
#'
#' @noRd