---
title: "Get started with roxygen2"
description: >
  Learn the big picture of roxygen2 and the basic workflow
  you'll use with it.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with roxygen2}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| include: false

knitr::opts_chunk$set(comment = "#>", collapse = TRUE)
```

Documentation is one of the most important aspects of good code.
Without it, users won't know how to use your package, and are unlikely to do so.
Documentation is also useful for you in the future (so you remember what the heck you were thinking!), and for other developers working on your package.
The goal of roxygen2 is to make documenting your code as easy as possible.

R provides a standard way of documenting packages: you write `.Rd` files in the `man/` directory.
These files use a custom syntax, loosely based on LaTeX.
roxygen2 provides a number of advantages over writing `.Rd` files by hand:

- Code and documentation are adjacent so when you modify your code, it's easy to remember that you need to update the documentation.

- roxygen2 dynamically inspects the objects that it's documenting, so it can automatically add data that you'd otherwise have to write by hand.

- It abstracts over the differences in documenting S3 and S4 methods, generics and classes, so you need to learn fewer details.

As well as generating `.Rd` files, roxygen will also create a `NAMESPACE` for you, and will manage the `Collate` field in `DESCRIPTION`.

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

## Running roxygen

There are three main ways to run roxygen:

- `roxygen2::roxygenise()`.

- `devtools::document()`.

- `Ctrl + Shift + D`, if you're using RStudio or Positron (with [RStudio keybindings](https://positron.posit.co/migrate-rstudio-keybindings.html) enabled).

You can mix handwritten Rd and roxygen2; roxygen2 will never overwrite a file it didn't create.

## Basic process: human readable documentation

There are three steps in the transformation from roxygen comments in your source file to human readable documentation:

1. You add roxygen comments to your source file.
2. `roxygen2::roxygenise()` converts roxygen comments to `.Rd` files.
3. R converts `.Rd` files to human readable documentation.

The process starts when you add specially formatted roxygen comments to your source file.
Roxygen comments start with `#'` so you can continue to use regular comments for other purposes.

```{r}
#| echo: false

example <- "#' Add together two numbers
#'
#' @param x A number.
#' @param y A number.
#' @return A number.
#' @export
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}
"
```

```{r, code=example}
```

For the example above, this will generate `man/add.Rd` that looks like:

```{r}
#| echo: false
#| results: "asis"

cat(
  "\x60\x60\x60rd\n",
  format(roxygen2::roc_proc_text(roxygen2::rd_roclet(), example)[[1]]),
  "\n\x60\x60\x60",
  sep = ""
)
```

Rd files are a special file format loosely based on LaTeX.
You can read more about the Rd format in the [R extensions](https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format) manual.
With roxygen2, there are few reasons to know about Rd files, so here I'll avoid discussing them as much as possible, focusing instead on what you need to know about roxygen2.

When you use `?x`, `help("x")` or `example("x")` R looks for an Rd file containing `\alias{x}`.
It then parses the file, converts it into HTML and displays it.
These functions look for an Rd file in *installed* packages.
This isn't very useful for package development, because you want to use the `.Rd` files in the *source* package.
For this reason, we recommend that you use roxygen2 in conjunction with devtools: `devtools::load_all()` automatically adds shims so that `?` and friends will look in the development package.

## Basic process: making functions available to users

The example above, that includes an `@export` tag to indicate the `add()` function should be part of the interface of the package available to users, would also be converted by `roxygenize()` into a line in the `NAMESPACE` file:

```{r}
#| echo: false
#| results: "asis"

cat(
  "\x60\x60\x60txt\n",
  roxygen2::roc_proc_text(roxygen2::namespace_roclet(), example),
  "\n\x60\x60\x60",
  sep = ""
)
```

## Learn more

The other vignettes provide more detail on the most important individual components:

- `vignette("rd-functions")` describes how to document your functions with roxygen2.

- `vignette("rd-datasets")` and `vignette("rd-packages")` cover documenting datasets and the package itself.

- `vignette("rd-S3")`, `vignette("rd-S4")`, `vignette("rd-R6")`, and `vignette("rd-S7")` discuss documenting the various OOP systems.

- `vignette("rd-formatting")` gives the details of roxygen2's rmarkdown support.

- `vignette("reuse")` demonstrates the tools available to reuse documentation in multiple places.

- `vignette("namespace")` describes how to generate a `NAMESPACE` file, how namespacing works in R, and how you can use roxygen2 to be specific about what your package needs and supplies.