5.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.
5.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.
5.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.
5.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.
5.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)
Do not use code font for package names. If package name is ambiguous in the context, disambiguate with words, e.g. “the foo package”.