rd.Rmd

---
title: "Documenting functions"
description: >
  The basics of roxygen2 tags and how to use them for 
  documenting functions.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Documenting functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(comment = "#>", collapse = TRUE)
```

This vignette introduces the basics of roxygen2 for documenting functions.
See `vignette("rd-other")` for documenting other types of objects and `vignette("reuse")` for reusing documentation across topics.

## Basics

A roxygen **block** is a sequence of lines starting with `#'` (optionally preceded by white space).

The first lines of the block is called the **introduction** and forms the title, description, and details, as described below.
The introduction continues until the first **tag**.

Tags start with `@`, like `@details` or `@param`.
Tags must appear at the beginning of a line and their content extends to the start of the next tag or the end of the block.
Text within the description or tags can be formatted using Markdown or `Rd` commands; see `vignette("rd-formatting")` for details.

A block ends when it hits R code, usually a function or object assignment.
Blocks ignore empty lines, including lines made up of non-roxygen comments.
If you need to separate two blocks, use `NULL`.

If you want to use roxygen2 documentation tags without generating an `.Rd` file, you can use `@noRd` to suppress file generation for a given topic. This is useful if you want to use roxygen2 conventions for documenting an internal function; only people reading the source doc will be able to read the docs.


## The introduction

Each documentation block starts with some text which defines the title, the description, and the details.
Here's an example showing what the documentation for `sum()` might look like if it had been written with roxygen:

```{r}
#' Sum of vector elements
#'
#' `sum` returns the sum of all the values present in its arguments.
#'
#' This is a generic function: methods can be defined for it directly
#' or via the [Summary()] group generic. For this to work properly,
#' the arguments `...` should be unnamed, and dispatch is on the
#' first argument.
sum <- function(..., na.rm = TRUE) {}
```

This introductory block is broken up as follows:

-   The first sentence is the **title**: that's what you see when you look at `help(package = mypackage)` and is shown at the top of each help file.
    It should generally fit on one line, be written in sentence case, and not end in a full stop.

-   The second paragraph is the **description**: this comes first in the documentation and should briefly describe what the function does.

-   The third and subsequent paragraphs go into the **details**: this is a (often long) section that comes after the argument description and should provide any other important details of how the function operates.
    The details are optional.

You can also use explicit `@title`, `@description`, and `@details` tags.
This is unnecessary unless you want to have a multi-paragraph description, bulleted list, or other more exotic structure.

```{r}
#' Sum of vector elements
#' 
#' @description
#' `sum` returns the sum of all the values present in its arguments.
#'
#' @details
#' This is a generic function: methods can be defined for it directly
#' or via the [Summary()] group generic. For this to work properly,
#' the arguments `...` should be unnamed, and dispatch is on the
#' first argument.
```

## Functions

Functions are the most commonly documented objects.
Functions require three tags: `@param`, `@returns`, and `@examples`.

### Inputs

Use `@param name description` to describe each input to the function.
The description should provide a succinct summary of parameter type (e.g. a string, a numeric vector), and if not obvious from the name, what the parameter does.
The description is a sentence so should start with a capital letter and end with a full stop.
It can span multiple lines (or even paragraphs) if necessary.
All parameters must be documented.

If two or more arguments are tightly coupled, you can document them in one place by separating the names with commas (no spaces).
For example, to document both `x` and `y`, you can say `@param x,y Numeric vectors`.

### Outputs

`@returns description` describes the output from the function.
Briefly describe the type/shape of the output, not the details.

All functions must have a documented return value for initial CRAN submission.

### Examples

`@examples` provides executable R code showing how to use the function in practice.
This is a very important part of the documentation because many people look at the examples before reading anything.
Example code must work without errors as it is run automatically as part of `R CMD check`.

For the purpose of illustration, it's often useful to include code that causes an error.
You can do this by wrapping the code in `try()` or using `\dontrun{}` to exclude from the executed example code.

For finer control, you can use `@examplesIf`:

``` r
#' @examplesIf interactive()
#' browseURL("https://roxygen2.r-lib.org")
```

This generates

    \examples{
    \dontshow{if (interactive() (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
    gh_organizations(since = 42)
    \dontshow{\}) # examplesIf}
    }

This way, the code evaluating whether the example can be run is not shown to users reading the help, but it still prevents R CMD check failures.

Instead of including examples directly in the documentation, you can put them in separate files and use `@example path/relative/to/package/root` to insert them into the documentation.

All functions must have examples for initial CRAN submission.

### Usage

In most case, the function usage (which appears beneath the description in the generates docs) will be automatically derived from the function specification.
For the cases where it is not, please [file an issue](https://github.com/r-lib/roxygen2/issues) and use `@usage` to override the default with what you want.
If you want to suppress the usage altogether (which is sometimes useful for internal or deprecated functions), you can use `@usage NULL`.