# Roxygen Quick Reference

`roxygen2` is an `R` package that allows you to write in-source documentation for your package functions and objects.

Write documentation above your package functions with the `#'` comment prefix.

### Documenting Functions

#### Example

    #' This is the title.
    #'
    #' This is the description.
    #'
    #' These are further details.
    #'
    #' @section A Custom Section:
    #'
    #' Text accompanying the custom section.
    #'
    #' @param x A description of the parameter 'x'. The
    #'   description can span multiple lines.
    #' @param y A description of the parameter 'y'.
    #'
    #' @export
    #'
    #' @examples
    #' add_numbers(1, 2) ## returns 3
    #'
    #' ## don't run this in calls to 'example(add_numbers)'
    #' \dontrun{
    #'    add_numbers(2, 3)
    #' }
    #'
    #' ## don't test this during 'R CMD check'
    #' \donttest{
    #'    add_numbers(4, 5)
    #' }
    add_numbers <- function(x, y) {
         x + y
    }

#### Common Tags

`@param <name> <description>` | Document a function parameter.
`@export` | Make this function available to users of your package.
`@examples <r-code>` | Inline R code showing how the function is used. Wrap code blocks in `\dontrun{}` to prevent them from running on calls to `example()`. Use `\donttest{}` to disable running this code in `R CMD check`.
`@return` | Describe what this function returns.
`@family <family-name>` | Automatically generate links to other functions within this family in the documentation's See Also section.
`@seealso` | Provide links to other resources that could help users understand how to use your function.
`@inheritParams <function>` | Re-use parameter documentation from another function. Use `@inheritParams <package::function>` to re-use documentation from a function in a separate package.
`@section <name>:` | Provide a custom section with the name `<name>`. The line must end with a colon (`:`).

In addition, you can use `@keywords internal` to ensure that documentation for a particular function is generated, but not added to the package index.

### Documenting Packages

By convention, package documentation is usually included in a file `R/<package-name>-package.R`. The `roxygen` block providing package documentation should contain the `@docType package` field declaration, and should end with `NULL`.

#### Example

    #' Package Name
    #'
    #' Package description.
    #'
    #' @docType package
    #' @name <package-name>
    #' @import assertthat
    #' @importFrom utils head tail
    #' @useDynLib <package-name>
    NULL

#### Common Tags

`@import <pkg>` | Import all symbols from a package, for use in your own package's functions.
`@importFrom <pkg> <symbols...>` | Selectively import symbols from a package, for use in your own package's functions.
`@useDynLib <own-pkg>` | Include this if your package contains C / C++ code.

### Rd Markup

Use `R Documentation` LaTeX-style markup to further style your documentation.

`\emph{}` | For italicized text.
`\strong{}` | For bold text.
`\code{}` `\preformatted{}` | For code snippets. Use `\code{}` for single-line code snippets, and `\preformatted{}` for blocks of code.
`\link{object}` `\link[=class]{object}` `\linkS4class{S4Class}` | Used to link to other `R` documentation. For example, use `\code{\link{rnorm}}` to link to the documentation associated with the `rnorm` function.
`\url{URL}` `\href{URL}{text}` | Link to content on the internet; for example, external documentation. Use `\href{URL}{text}` if you want the displayed text to differ from the linked URL.

`\enumerate{<items...>}`
`\itemize{<items...>}`
`\describe{<items...>}`

Provide a list of items. `\enumerate{}` delimits entries with sequential numbers, while `\itemize{}` delimits entries with bullets.

    \enumerate{
       \item Item 1.
       \item Item 2.
       \item Item 3.
    }

`\describe{}` differs in that items are specified with labels as well as text, e.g.

    \describe{
       \item{label-1}{text-1}
       \item{label-2}{text-2}
    }

`\tabular{alignment}{text}`

Provide a table of text.

Separate fields with `\tab`, and rows with `\cr`. `alignment` is a string of `l` / `c` / `r`, indicating left, center, and right alignment respectively. There should be one letter for each column in the table.

    \tabular{rl}{
       Entry 1 \tab Entry 2 \cr
       Entry 3 \tab Entry 4 \cr
    }

### Learning More

Read Hadley Wickham's guide in R Packages to learn more about how to use `roxygen2` and `devtools` to produce documentation for your R packages.

Read the `roxygen` vignettes: start with the introductory vignette with `vignette("roxygen2")`, and view other available vignettes with `vignette(package = "roxygen2")`.

Read R-exts for a comprehensive guide to `.Rd` documentation and the set of available tags (which are understood by `roxygen` as well).