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 (.).

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.

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.

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.

Use line breaks before/after sections where needed:

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.

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.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:

More recommendations should be organised in a bulleted list:

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.

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.