Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
4 contributors

Users who have contributed to this file

@hadley @yihui @PeteHaitch @dlebauer
153 lines (119 sloc) 5.8 KB
---
title: "Introduction to roxygen2"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting 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`.
This vignette provides a high-level description of roxygen2 and how the three main components work. The other vignettes provide more detail on the most important individual components:
* [Generating .Rd files](rd.html) and [text formatting](rd-formatting.html)
describe how to generate function documentation via `.Rd` files
* [Managing your `NAMESPACE`](namespace.html) 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.
* See [update_collate()] for the details of `@include`, which for complicated
reasons is not implemented as a roclet.
## Running roxygen
There are three main ways to run roxygen:
* `roxygen2::roxygenise()`.
* `devtools::document()`.
* `Ctrl + Shift + D`, if you're using RStudio.
You can mix hand written Rd and roxygen2; roxygen2 will never overwrite a file it didn't create.
## Basic process
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}
#' Add together two numbers
#'
#' @param x A number
#' @param y A number
#' @return The sum of \code{x} and \code{y}
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
x + y
}
```
For the example, above, this will generate `man/add.Rd` that looks like:
```
% Generated by roxygen2 (3.2.0): do not edit by hand
\name{add}
\alias{add}
\title{Add together two numbers}
\usage{
add(x, y)
}
\arguments{
\item{x}{A number}
\item{y}{A number}
}
\value{
The sum of \code{x} and \code{y}
}
\description{
Add together two numbers
}
\examples{
add(1, 1)
add(10, 1)
}
```
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, focussing 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. Note, however, that this preview does not work with intra-package links. To preview those, you'll need to install the package. If you use RStudio, the easiest way to do this is to click the "Build & Reload button".
### RCpp
You can also use roxygen2 with Rcpp. Simply include roxygen2 comments in your C++ code (using `//` instead of `#`), and Rcpp will automatically carry the comments along into `RcppExports.R` where roxygen2 will find them.
For example, dplyr has `between.cpp` which starts:
```cpp
//' Do values in a numeric vector fall in specified range?
//'
//' This is a shortcut for `x >= left & x <= right`, implemented
//' efficiently in C++ for local values, and translated to the
//' appropriate SQL for remote tables.
//'
//' @param x A numeric vector of values
//' @param left,right Boundary values
//' @export
//' @examples
//' between(1:12, 7, 9)
//'
//' x <- rnorm(1e2)
//' x[between(x, -1, 1)]
// [[Rcpp::export(rng = false)]]
Rcpp::LogicalVector between(Rcpp::NumericVector x, double left, double right) {
}
```
This is automatically translated to the following R code in `RcppExports.R`:
```{r, eval = FALSE}
#' Do values in a numeric vector fall in specified range?
#'
#' This is a shortcut for `x >= left & x <= right`, implemented
#' efficiently in C++ for local values, and translated to the
#' appropriate SQL for remote tables.
#'
#' @param x A numeric vector of values
#' @param left,right Boundary values
#' @export
#' @examples
#' between(1:12, 7, 9)
#'
#' x <- rnorm(1e2)
#' x[between(x, -1, 1)]
between <- function(x, left, right) {
}
```
You can’t perform that action at this time.