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 (
There is no need to use the explicit
@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
Alternatively, tags that span over multiple lines (like
@section) can have the corresponding tag on its own line and then subsequent lines don’t need to be indented.
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
@return, the text should be a
sentence, starting with a capital letter and ending with a full stop.
If some functions share parameters, you can use
@inheritParams to avoid
duplication of content in multiple places.
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.
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
- Function arguments, e.g.
- Values, e.g.
- Literal R code, e.g.
mean(x, na.rm = TRUE)
- Class names, e.g. “a tibble will have class
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.