documentation.Rmd

# Documentation

## Introduction

Documentation of code is essential, even if the only person using your code 
is future-you. Use [roxygen2](https://github.com/klutometis/roxygen) with 
[markdown](https://github.com/klutometis/roxygen/blob/master/vignettes/markdown.Rmd)
support enabled to keep your documentation close to the code.

```{r, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```

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

```{r}
#' 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.

```{r}
#' 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.
```

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

```{r}
#' @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.

```{r}
#' @examples
#' 1 + 1
#' sin(pi)
```

Use line breaks before/after sections where needed:

```{r}
#' @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.
```

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

```{r}
#' @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.

```{r}
#' @inheritParams argument function_to_inherit_from
```

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

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

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

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

More recommendations should be organised in a bulleted list:

```{r}
#' @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.

```{r}
#' @family single table verbs
```

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

## Internal functions

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

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