[](https://CRAN.R-project.org/package=roxygen2)
[](https://github.com/r-lib/roxygen2/actions)
[](https://codecov.io/gh/r-lib/roxygen2?branch=master)
The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to automatically generate `.Rd` files in `man/`, `NAMESPACE`, and, if needed, the `Collate` field in `DESCRIPTION`.
## Installation
```R
# Install devtools from CRAN
install.packages("roxygen2")
# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/roxygen2")
```
## Usage
The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in the `man/` directory. Here's a [simple example](https://stringr.tidyverse.org/reference/str_length.html) from the stringr package:
```R
#' The length of a string
#'
#' Technically this returns the number of "code points", in a string. One
#' code point usually corresponds to one character, but not always. For example,
#' an u with a umlaut might be represented as a single character or as the
#' combination a u and an umlaut.
#'
#' @inheritParams str_detect
#' @return A numeric vector giving number of characters (code points) in each
#' element of the character vector. Missing string have missing length.
#' @seealso [stringi::stri_length()] which this function wraps.
#' @export
#' @examples
#' str_length(letters)
#' str_length(NA)
#' str_length(factor("abc"))
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
}
```
When you `roxygenise()` (or `devtools::document()`) your package these comments will be automatically transformed to the `.Rd` that R uses to generate the documentation you see when you type `?str_length`.
## Learn more
To get started, first read `vignette("roxygen2")`. Then read more about the specific package component that you want to generate:
* For `.Rd` documentation files, read `vignette("rd")`.
* For the `NAMESPACE`, read `vignette("namespace")`.
* For the `Collate` field in the `DESCRIPTION`, read `update_collate()`.
roxygen2/man/ 0000755 0001762 0000144 00000000000 14047223751 012607 5 ustar ligges users roxygen2/man/load_options.Rd 0000644 0001762 0000144 00000003343 13675431642 015601 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/options.R
\name{load_options}
\alias{load_options}
\alias{roxy_meta_get}
\title{Load roxygen2 options}
\usage{
load_options(base_path = ".")
roxy_meta_get(key = NULL, default = NULL)
}
\arguments{
\item{base_path}{Path to package.}
}
\description{
Options can be stored in the \code{Roxygen} field of the \code{DESCRIPTION}, or
in \code{man/roxygen/meta.R}. In either case, the code is parsed and evaluated
in a child of the base environment. Call \code{roxy_meta_get()} to access
current option values from within tag and roclet methods.
Options in \code{man/roxygen/meta.R} override those present in \code{DESCRIPTION}.
}
\section{Possible options}{
\itemize{
\item \code{roclets} \verb{| Command | example | help | R CMD check | R CMD check –as-cran |
|---|---|---|---|---|
\dontrun{} |
x | |||
\dontshow{} |
x | x | x | |
\donttest{} |
x | x | x |
Note that R CMD check --as-cran is run for incoming CRAN checks but not for regular CRAN checks.
For finer control you can use `@examplesIf
#' @examplesIf interactive()
#' browseURL("https://roxygen2.r-lib.org")will generate
\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.
@return description describes the output from the function. This is not always necessary, but is a good idea if you return different types of outputs depending on the input, or you’re returning an S3, S4 or RC object.
We could use these new tags to improve our documentation of sum() as follows:
#' 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.
#'
#' @param ... Numeric, complex, or logical vectors.
#' @param na.rm A logical scalar. Should missing values (including `NaN`)
#' be removed?
#' @return If all inputs are integer and logical, then the output
#' will be an integer. If integer overflow
#' (<http://en.wikipedia.org/wiki/Integer_overflow>) occurs, the output
#' will be NA with a warning. Otherwise it will be a length-one numeric or
#' complex vector.
#'
#' Zero-length vectors have sum 0 by definition. See
#' <http://en.wikipedia.org/wiki/Empty_sum> for more details.
#' @examples
#' sum(1:10)
#' sum(1:5, 6:10)
#' sum(F, F, F, T, T)
#'
#' sum(.Machine$integer.max, 1L)
#' sum(.Machine$integer.max, 1)
#'
#' \dontrun{
#' sum("a")
#' }
sum <- function(..., na.rm = TRUE) {}Indent the second and subsequent lines of a tag so that when scanning the documentation so it’s easy to see where one tag ends and the next begins. Tags that always span multiple lines (like @example) should start on a new line and don’t need to be indented.
S3 generics are regular functions, so document them as such. If necessary, include a @section that provides additional details for method implementors
S3 classes have no formal definition, so document the constructor.
It is your choice whether or not to document S3 methods. Generally, it’s not necessary to document straightforward methods for common generics like print(). (You should, however, always @export S3 methods).
If your method is more complicated, you should document it by setting @rdname. Typically you will document methods with their generic, so you’d document foofy.data.frame by setting @rdname. In base R, you can find documentation for more complex methods like ?predict.lm, ?predict.glm, and ?anova.glm.
Generally, roxygen2 will automatically figure out the generic that the method belongs to, and you should only need to use @method if there is ambiguity. For example, is all.equal.data.frame() the equal.data.frame method for all(), or the data.frame method for all.equal()?. If this happens to you, disambiguate with (e.g.) @method all.equal data.frame.
S4 generics are also functions, so document them as such.
Document S4 classes by adding a roxygen block before setClass(). Use @slot to document the slots of the class. Here’s a simple example:
#' An S4 class to represent a bank account
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
slots = list(balance = "numeric")
)S4 methods are a little more complicated. Unlike S3 methods, all S4 methods must be documented. You can document them in three places:
In the class. Most appropriate if the corresponding generic uses single dispatch and you created the class.
In the generic. Most appropriate if the generic uses multiple dispatch and you control it.
In its own file. Most appropriate if the method is complex. or the either two options don’t apply.
Use either @rdname or @describeIn to control where method documentation goes. See the next section for more details.
Starting from version 7.0.0 roxygen treats documentation for R6 classes specially:
R6 methods can be documented in-line, i.e. the method’s documentation comments come right before the definition of the method.
Method documentation can use the @description, @details, @param, @return and @examples tags. These are used to create a subsection for the method, within a separate ‘Methods’ section. All roxygen comment lines of a method documentation must appear after a tag.
@param tags that appear before the class definition are automatically inherited by all methods, if needed.
R6 fields and active bindings can make use of the @field tag. Their documentation should also be in-line.
Roxygen2 checks that all public methods, public fields, active bindings and all method arguments are documented, and issues warnings otherwise.
To turn off the special handling of R6 classes and go back to the roxygen2 6.x.x behavior, use the r6 = FALSE option in DESCRIPTION, in the Roxygen entry: Roxygen: list(r6 = FALSE).
Roxygen2 automatically generates additional sections for an R6 class:
A section with information about the superclass(es) of the class, with links. In HTML this includes a list of all inherited methods, with links.
An ‘Examples’ section that contains all class and method examples. This section is run by R CMD check, so method examples must work without errors.
An example from the R6 tutorial:
#' R6 Class Representing a Person
#'
#' @description
#' A person has a name and a hair color.
#'
#' @details
#' A person can also greet you.
Person <- R6::R6Class("Person",
public = list(
#' @field name First or full name of the person.
name = NULL,
#' @field hair Hair color of the person.
hair = NULL,
#' @description
#' Create a new person object.
#' @param name Name.
#' @param hair Hair color.
#' @return A new `Person` object.
initialize = function(name = NA, hair = NA) {
self$name <- name
self$hair <- hair
self$greet()
},
#' @description
#' Change hair color.
#' @param val New hair color.
#' @examples
#' P <- Person("Ann", "black")
#' P$hair
#' P$set_hair("red")
#' P$hair
set_hair = function(val) {
self$hair <- val
},
#' @description
#' Say hi.
greet = function() {
cat(paste0("Hello, my name is ", self$name, ".\n"))
}
)
)Datasets are usually stored as .rdata files in data/ and not as regular R objects in the package. This means you need to document them slightly differently: instead of documenting the data directly, you quote the dataset’s name.
#' Prices of 50,000 round cut diamonds
#'
#' A dataset containing the prices and other attributes of almost 54,000
#' diamonds.
#'
#' @format A data frame with 53940 rows and 10 variables
#' \describe{
#' \item{price}{price in US dollars (\$326--\$18,823)}
#' \item{carat}{weight of the diamond (0.2--5.01)}
#' \item{cut}{quality of the cut (Fair, Good, Very Good, Premium, Ideal)}
#' \item{color}{diamond colour, from D (best) to J (worst)}
#' \item{clarity}{a measurement of how clear the diamond is (I1 (worst), SI2,
#' SI1, VS2, VS1, VVS2, VVS1, IF (best))}
#' \item{x}{length in mm (0--10.74)}
#' \item{y}{width in mm (0--58.9)}
#' \item{z}{depth in mm (0--31.8)}
#' \item{depth}{total depth percentage = z / mean(x, y) = 2 * z / (x + y) (43--79)}
#' \item{table}{width of top of diamond relative to widest point (43--95)}
#' }
#' @source <http://www.diamondse.info/>
"diamonds"
#> [1] "diamonds"Note the use of two additional tags that are particularly useful for documenting data:
@format, which gives an overview of the structure of the dataset. This should include a definition list that describes each variable. There’s currently no way to generate this with markdown, so this is one of the few places you’ll need to Rd markup directly.
@source where you got the data form, often a URL.
As well as documenting every object inside the package, you can also document the package itself by documenting the special sentinel "_PACKAGE". We recommend placing package documentation in {pkgname}-package.R, and have @keywords internal. Here’s an example:
#' @details
#' The only function you're likely to need from roxygen2 is [roxygenize()].
#' Otherwise refer to the vignettes to see how to format the documentation.
#' @keywords internal
"_PACKAGE"Package documentation is a good place to put @section Package options: that documents options used by the package.
Some notes:
Package documentation will automatically include information parsed from the DESCRIPTION, including title, description, list of authors, and useful URLs.
By default, aliases will be added so that both ?pkgname and package?pkgname will find the package help. If there’s an existing function called pkgname, use @aliases {pkgname}-package to override the default.
usethis::use_package_doc() will generate a basic template to get you started.
Use @references to point to published material about the package that users might find helpful.
You can add arbitrary sections with the @section tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case, must fit on one line, and must be followed by a colon.
#' @section Warning:
#' Do not operate heavy machinery within 8 hours of using this function.You can also create sections using the markdown syntax for headers. For example, the previously-defined section can be created with markdown headers like this:
#' @details # Warning
#' Do not operate heavy machinery within 8 hours of using this function.Note that ‘#’ may only appear after the @description and @details tags. Since @details can appear multiple times in a block, you can always precede a ‘#’ section with @details.
To add a subsection, use level two or greater headings:
#' @details # Warning
#' You must not call this function unless ...
#'
#' ## Exceptions
#' Apart from the following special cases...If you find yourself adding a lot of sections, you might consider using a vignette instead.
There is a tension between the DRY (do not repeat yourself) principle of programming and the need for documentation to be self-contained. It’s frustrating to have to navigate through multiple help files in order to pull together all the pieces you need. Roxygen2 provides several ways to avoid repeating yourself in code documentation, while assembling information from multiple places in one documentation file:
Cross-link documentation files with @seealso and @family.
Inherit documentation from another topic with
@inherit, @inheritParams, and @inheritSection.
Document multiple functions in the same topic with @describeIn or @rdname.
Run arbitrary R code with the markdown markup for inline code, see section ‘Dynamic R code’ in vignette("rd-formatting").
Run arbitrary R code with @eval.
Create reusable templates with @template and @templateVar.
There are two tags that make it easier for people to navigate around your documentation: @seealso and @family. @seealso allows you to point to other useful resources, either on the web <http://www.r-project.org> or to other documentation with [function_name()]. If you have a family of related functions, you can use @family {family} to cross-reference each function to every other function within the family. A function can be a member of multiple families.
For sum(), this might look like:
#' @family aggregations
#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and
#' [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.By default @family {family}, will generate the see also text “Other {family}:”, so the @family name should be plural (i.e., “model building helpers” not “model building helper”). You can override the default title by providing a rd_family_title list in man/roxygen/meta.R:
list(
rd_family_title = list(aggregations = "Aggregation functions")
)You can inherit documentation from other functions in a few ways:
@inherit source_function will inherit parameters, return, references, description, details, sections, and seealso from source_function().
@inherit source_function return details will inherit selected components from source_function()
@inheritParams source_function inherits just the parameter documentation from source_function().
@inheritSection source_function Section title will inherit the single @section called “Section title” from source_function().
All of these work recursively so you can inherit documentation from a function that has inherited it from elsewhere.
You can also inherit documentation from functions provided by another package by using pkg::source_function.
You can document multiple functions in the same file by using either @rdname or @describeIn tag. It’s a technique best used with care: documenting too many functions in one place leads to confusion. Use it when all functions have the same (or very similar) arguments.
@describeIn@describeIn is designed for the most common cases:
It generates a new section, named either “Methods (by class)”, “Methods (by generic)” or “Functions”. The section contains a bulleted list describing each function, labelled so that you know what function or method it’s talking about. Here’s an example, documenting an imaginary new generic:
#' Foo bar generic
#'
#' @param x Object to foo.
foobar <- function(x) UseMethod("x")
#' @describeIn foobar Difference between the mean and the median
foobar.numeric <- function(x) abs(mean(x) - median(x))
#' @describeIn foobar First and last values pasted together in a string.
foobar.character <- function(x) paste0(x[1], "-", x[length(x)])@rdname@rdname is a more general purpose tool. It overrides the default file name generated by roxygen and merges documentation for multiple objects into one file. This gives you complete freedom to combine documentation however you see fit. There are two ways to use @rdname. You can add documentation to an existing function:
#' Basic arithmetic
#'
#' @param x,y numeric vectors.
add <- function(x, y) x + y
#' @rdname add
times <- function(x, y) x * yOr, you can create a dummy documentation file by documenting NULL and setting an informative @name.
#' Basic arithmetic
#'
#' @param x,y numeric vectors.
#' @name arith
NULL
#> NULL
#' @rdname arith
add <- function(x, y) x + y
#' @rdname arith
times <- function(x, y) x * yBy default, roxygen blocks are processed in the order in which they appear in the file. When you’re combining multiple files, this can sometimes cause the function usage to appear in a suboptimal order. You can override the default ordering with @order. For example, the following the block would place times first in arith.Rd because 1 comes before 2.
#' @rdname arith
#' @order 2
add <- function(x, y) x + y
#' @rdname arith
#' @order 1
times <- function(x, y) x * yAnother technique is the @eval tag. It evaluates code and treatments the result as if it was a literal roxygen tags. This makes it possible to eliminate duplication by writing functions. The code will be evaluated in the package environment and should yield a character vector of roxygen comments (but without the leading #').
For example, this code + roxygen block:
my_params <- function() {
c(
"@param x An integer vector",
"@param y A character vector"
)
}
#' A title
#'
#' @eval my_params()
#' @export
foo <- function(x, y) {
}Is equivalent to:
#' A title
#'
#' @param x An integer vector
#' @param y A character vector
#' @export
foo <- function(x, y) {
}Note that @eval cannot be embedded into another roxygen tag. If you want to dynamically generate part of a roxygen tag, see section ‘Dynamic R code’ in vignette("rd-formatting").
A related function is @evalRd. It works in the same way as @eval (i.e. it’s evaluated in the package environment) but rather than yielding roxygen comments that are processed as if they had been typed directly, it yields top-level Rd code that is inserted directly into the generated .Rd file. It is primarily useful if you want to generate Rd structure that is not currently supported by roxygen2.
For example, this block:
my_note <- function(x) {
paste0("\\note{", paste0(x, "\n", collapse =""), "}")
}
#' @evalRd my_note(c(
#' "This is the first line",
#' "This is the second line"
#' ))
NULL
#> NULLWould generate this Rd:
\note{
This is the first line
This is the second line
}Roxygen templates are R files that contain only roxygen comments and that live in the man-roxygen directory. Use @template file-name (without extension) to insert the contents of a template into the current documentation.
You can make templates more flexible by using template variables defined with @templateVar name value. Template files are run with brew, so you can retrieve values (or execute any other arbitrary R code) with <%= name %>.
Note that templates are parsed a little differently to regular blocks, so you’ll need to explicitly set the title, description and details with @title, @description and @details.
.Rmd/.md filesStarting from roxygen2 7.0.0, you can use @includeRmd path/to/file.Rmd to include an external .Rmd or .md document into a manual page (the path is relative from the source package root directory). You can include the same file in multiple documentation files, and for the first time, share content across documentation and vignettes.
@includeRmd supports headings in the external Rmd. The rules are as follows:
All text before the first level 1 heading (i.e. #), is added to the details section. If you prefer a different section, then write the name of the section after the path in the @includeRmd tag, in all lowercase. Example: @includeRmd path description. This currently does not work with user defined sections (created with @section).
Level 1 headings generate their own section (\section{}).
Other headings (level 2 and so on) create subsections (\subsection{}) within the section they appear in.
All content in the Rmd file will go either in the details or in new top level sections. It is currently not possible to document function arguments, return values, etc. in external Rmd documents.
The included Rmd file can have roxygen markdown style links to other help topics. E.g. [roxygen2::roxygenize()] will link to the manual page of the roxygenize function in roxygen2. See vignette("rd-formatting") for details.
@includeRmd tries to set up knitr to support caching in the Rmd file. It sets the cache path to the default knitr cache path of the included Rmd file (i.e. foo/bar/file_cache/ for foo/bar/file.Rmd), so if you do not change the cache path within the Rmd itself, then everything should work out of the box. You should add these cache paths to .gitignore and .Rbuildignore.
@includeRmd also sets the knitr figure path of the (fig.path) to the default figure path of the included Rmd. Overriding this default is unlikely to work.
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 and text formatting describe how to generate function documentation via .Rd files
Managing your 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.
See [update_collate()] for the details of @include, which for complicated reasons is not implemented as a roclet.
There are three main ways to run roxygen:
roxygen2::roxygenise().
devtools::document().
Ctrl + Shift + D, if you’re using RStudio.
You can mix handwritten Rd and roxygen2; roxygen2 will never overwrite a file it didn’t create.
There are three steps in the transformation from roxygen comments in your source file to human readable documentation:
roxygen2::roxygenise() converts roxygen comments to .Rd files..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.
#' 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 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”.
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:
//' 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:
#' 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) {
}Starting from version 6.0.0, roxygen supports markdown markup within most roxygen tags. Roxygen uses the commonmark package, which is based on the CommonMark Reference Implementation to parse these tags. See https://commonmark.org/help/ for more about the parser and the markdown language it supports. You can also still use the .Rd syntax, some of which we will present below in the Rd syntax section.
There are two ways to turn on markdown support for a package: globally, at the package level, and locally at the block level.
To turn on markdown for the whole package, insert this entry into the DESCRIPTION file of the package:
Roxygen: list(markdown = TRUE)The position of the entry in the file does not matter. After this, all Roxygen documentation will be parsed as markdown.
Alternatively, you can use the @md tag to turn on markdown support for a single documentation chunk. This is a good option to write any new documentation for existing packages in markdown.
There is also a new @noMd tag. Use this if you turned on markdown parsing globally, but need to avoid it for a single chunk. This tag is handy if the markdown parser interferes with more complex Rd syntax.
Here is an example roxygen chunk that uses markdown.
#' Use roxygen to document a package
#'
#' This function is a wrapper for the [roxygen2::roxygenize()] function from
#' the roxygen2 package. See the documentation and vignettes of
#' that package to learn how to use roxygen.
#'
#' @param pkg package description, can be path or package name. See
#' [as.package()] for more information
#' @param clean,reload Deprecated.
#' @inheritParams roxygen2::roxygenise
#' @seealso [roxygen2::roxygenize()], `browseVignettes("roxygen2")`
#' @export
#' @mdThe usual markdown heading markup creates sections and subsections. Top level headings, i.e. ‘#’ create sections, via the \section{} Rd tag. ‘#’ may only appear after the @description and @details tags. Since @details can appear multiple times in a block, you can always precede a ‘#’ section with @details, if you prefer to place it towards the end of the block, after @return for example:
#' @details
#' Trim the leading and trailing whitespace from a character vector.
#'
#' @param x Character vector.
#' @return Character vector, with the whitespace trimmed.
#'
#' @details # This will be a new section
#' ...Top level sections are always placed at a fixed position in the manual page, after the parameters and the details, but before \note{}, \seealso{} and the \examples{}. Their order will be the same as in the roxygen block.
Headings at level two and above may appear inside any roxygen tag that formats lines of text. E.g. @description, @details, @return, etc. They create subsections, via the \subsection{} Rd tag. They are allowed within top level sections as well, i.e. after ‘#’. Subsections can be nested. Example:
#' @details
#' ## Subsection within details
#' ### Sub-subsection
#' ... text ...Emphasis and strong (bold) text are supported. For emphasis, put the text between asterisks or underline characters. For strong text, use two asterisks at both sides.
#' @references
#' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple
#' linear-time algorithms to test chordality of graphs, test acyclicity
#' of hypergraphs, and selectively reduce acyclic hypergraphs.
#' *SIAM Journal of Computation* **13**, 566-579.#' See `::is_falsy` for the definition of what is _falsy_
#' and what is _truthy_.Inline code is supported via backticks.
#' @param ns Optionally, a named vector giving prefix-url pairs, as
#' produced by `xml_ns`. If provided, all names will be explicitly
#' qualified with the ns prefix, i.e. if the element `bar` is defined ...You can also use this syntax to run custom R code and insert its output into the manual page. See section ‘Dynamic R code’ below.
For blocks of code, put your code between triple backticks:
#' ```
#' pkg <- make_packages(
#' foo1 = { f <- function() print("hello!") ; d <- 1:10 },
#' foo2 = { f <- function() print("hello again!") ; d <- 11:20 }
#' )
#' foo1::f()
#' foo2::f()
#' foo1::d
#' foo2::d
#' dispose_packages(pkg)
#' ```Note that this is not needed in @examples, since its contents are formatted as R code, anyway.
You can use similar syntax to include a block of R code and/or its output in the manual page. See section ‘Dynamic R code’ below.
Regular Markdown lists are recognized and converted to \enumerate{} or \itemize{} lists:
#' There are two ways to use this function:
#' 1. If its first argument is not named, then it returns a function
#' that can be used to color strings.
#' 1. If its first argument is named, then it also creates a
#' style with the given name. This style can be used in
#' `style`. One can still use the return value
#' of the function, to create a style function.#' The style (the `...` argument) can be anything of the
#' following:
#' * An R color name, see `colors()`.
#' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means
#' red. Transparency (alpha channel) values are ignored.
#' * A one-column matrix with three rows for the red, green
#' and blue channels, as returned by [grDevices::col2rgb()]Nested lists are also supported.
Note that you do not have to leave an empty line before the list. This is different from some markdown parsers.
Use GFM table formatting:
| foo | bar |
| --- | --- |
| baz | bim |By default, columns are left-aligned. Use colons to generate right and center aligned columns:
| left | center | right |
| :--- | :----: | ----: |
| 1 | 2 | 3 |Markdown hyperlinks work as usual:
#' See more about the markdown markup at the
#' [Commonmark web site](http://commonmark.org/help)URLs inside angle brackets are also automatically converted to hyperlinks:
#' The main R web site is at <https://r-project.org>.Markdown notation can also be used to create links to other help topics. There are two basic forms:
[ref]: The target topic and the link text are one and the same.[text][ref]: Link text differs from the target.First we explore the simplest form: [ref]. The presence of trailing parentheses, e.g., [func()], signals that the target func is a function, which causes two things to happen:
func() is automatically typeset as code.[ref]examples |
Links to help topic for … |
Notes |
|---|---|---|
[func()][pkg::func()] |
a function in same package or in pkg |
Always typeset as code. Produces Rd: \code{\link[=func]{func()}}or \code{\link[pkg:func]{pkg::func()}} |
[thing][pkg::thing] |
a topic in same package or in pkg |
Use for a topic that documents NULL and name is setvia @name, e.g., a dataset or concept.Not typeset as code. Produces Rd: \link{thing} or\link[pkg:thing]{pkg::thing} |
[`thing`][`pkg::thing`] |
a topic in same package or in pkg |
Same as above, but explicit backticks mean that it is typeset as code. Good for documenting a class. Produces Rd: \code{\link{thing}} or\code{\link[pkg:thing]{pkg::thing}} |
Use the second form [text][ref] to link to the topic specified by ref, but with text as the link text.
[text][ref]examples |
Links to help topic for … |
Notes |
|---|---|---|
[text][func()][text][pkg::func()] |
a function in same package or in pkg |
Text is not typeset as code. Produces Rd: \link[=func]{text} or\link[pkg:func]{text} |
[text][thing][text][pkg::thing] |
a topic in same package or in pkg |
Text is not typeset as code. Use for a topic that documents NULLand name is set via @name,e.g., a dataset or concept. Produces Rd: \link[=thing]{text} or\link[pkg:thing]{text} |
In the [text][ref], the link text is treated like normal text by default.
[`text`][ref].It is never appropriate to use backticks around the ref in this form.
[text][`blah-blah`][text][blah-blah]S3 and S4 class not done yet
| Examples | Help topic for what? |
Notes |
|---|---|---|
[abc-class][pkg::abc-class] |
an S4 class named “abc” in same package or in pkg |
In Rd: \linkS4class{abc} or\link[pkg:abc-class]{pkg::abc} |
[abc][abc-class] |
*is this a thing? | ??? \link[=abc-class]{abc} |
Markdown syntax for inline images works. The image files must be in the man/figures directory:
#' Here is an example plot:
#' Similarly to the knitr package, you can use the markdown inline code markup or markdown code blocks to evaluate R code and insert its output into the manual page.
To do this, prefix the code with r, i.e. the lowercase letter ‘r’ and a space character. Roxygen will interpret the rest of the text within backticks as R code and evaluate it, and replace the backtick expression with its value. After all such substitutions, the text of the whole tag is interpreted as markdown, as usual.
For example, the following will insert the date and the R version of the roxygen run.
#' Roxygen created this manual page on `r Sys.Date()` using R version
#' `r getRversion()`.The value of the R expression is converted to a character string, with paste(collapse = "\n"). So you don’t need explicitly convert to a character value, numeric values or any R object with an as.character() S3 method is fine. Also, you can insert multiple lines by returning a character vector. If you want to run R code without inserting any output, return an empty string or NULL.
The value of the expression is inserted into the text of the tag without interpreting it, before the markdown to .Rd conversion, so you can create markdown markup dynamically:
#' The `iris` data set has `r ncol(iris)` columns:
#' `r paste0("``", colnames(iris), "``", collapse = ", ")`.Note that you need to escape backtick characters, if they appear in the R expression, by doubling them, like above. The result after the dynamic R code evaluation will be:
The `iris` data set has 5 columns:
`Sepal.Length`, `Sepal.Width`, `Petal.Length`, `Petal.Width`, `Species`.And the final result in the .Rd file will look as:
The \code{iris} data set has 5 columns:
\code{Sepal.Length}, \code{Sepal.Width}, \code{Petal.Length}, \code{Petal.Width}, \code{Species}.The R code is evaluated in a new environment that is the child of the package environment of the package you are documenting. This means that you can call (internal or exported) functions of the package. packageName() will also report the name of the package:
#' To insert the name of the current package: `r packageName()`.A new evaluation environment is created for each roxygen block. So the output of this code:
#' @title ... `r myvar <- "foo"; NULL` `r myvar`
#'
#' @description ... `r myvar`will be:
#' @title ... foo
#'
#' @description ... fooCurrently the whole code expression must be on the same line, multi-line expressions are not supported.
Markdown code blocks can be dynamic as well, if you use ```{r} to start them, just like in knitr documents.
#' ```{r}
#' # This block of code will be evaluated
#' summary(iris)
#' ```Within a roxygen block, code blocks and inline code use the same evaluation environment, so variables created in one of them can be used in others.
Code blocks support knitr chunk options, e.g. to keep the output of several expressions together, you can specify results= "hold":
#' ```{r results = "hold"}
#' names(mtcars)
#' nrow(mtcars)
#' ```Plots will create .png files in the man/figures directory. The file names are created from the chunk names:
#' ```{r iris-pairs-plot}
#' pairs(iris[1:4], main = "Anderson's Iris Data -- 3 species",
#' pch = 21, bg = c("red", "green3", "blue")[unclass(iris$Species)])
#' ```Note that the generated .png files will be added to the package, and they can considerably increase the size of the package.
Note that code block support is currently experimental, and somewhat limited. Some of the known limitations:
error, fig.path, fig.process.roxygenize() (or devtools::document()) to generated the Rd files. This potentially makes roxygenize() (much) slower. You can turn on knitr caching as usual, but make sure to omit the cache from the package.Rd markupNote that turning on markdown does not turn off the standard Rd syntax. We suggest that you use the regular Rd tags in a markdown roxygen chunk only if necessary. The two parsers do occasionally interact, and the markdown parser can pick up and reformat Rd syntax, causing an error, or corrupted manuals.
Leading whitespace is interpreted by the commonmark parser, whereas it is ignored by the Rd parser (except in \preformatted{}). Make sure that you only include leading whitespace intentionally, for example for nested lists.
The Commonmark parser does not require an empty line before lists, and this might lead to unintended lists if a line starts with a number followed by a dot, or with an asterisk followed by whitespace:
#' You can see more about this topic in the book cited below, on page
#' 42. Clearly, the numbered list that starts here is not intentional.Links to operators or objects that contain special characters, do not work currently. E.g. to link to the %>% operator in the magrittr package, instead of [magrittr::%>%], you will need to use the Rd notation: \code{\link[magrittr]{\%>\%}}.
Within roxygen tags, you can use .Rd syntax to format text. Below we show you examples of the most important .Rd markup commands. The full details are described in R extensions. Before roxygen version 6.0.0 this was the only supported syntax. Now all of the formatting described below can be achived more easily with markdown syntax, with the important exception of mathematical expressions.
Note that \ and % are special characters. To insert literals, escape with a backslash: \\, \%.
\emph{italics}
\strong{bold}
\code{r_function_call(with = "arguments")}, \code{NULL}, \code{TRUE}
\pkg{package_name}
To other documentation:
\code{\link{function}}: function in this package
\code{\link[MASS]{abbey}}: function in another package
\link[=dest]{name}: link to dest, but show name
\code{\link[MASS:abbey]{name}}: link to function in another package, but show name.
\linkS4class{abc}: link to an S4 class
To the web:
\url{http://rstudio.com}
\href{http://rstudio.com}{Rstudio}
\email{hadley@@rstudio.com} (note the doubled @)
Ordered (numbered) lists:
#' \enumerate{
#' \item First item
#' \item Second item
#' }Unordered (bulleted) lists
#' \itemize{
#' \item First item
#' \item Second item
#' }Definition (named) lists
#' \describe{
#' \item{One}{First item}
#' \item{Two}{Second item}
#' }Standard LaTeX (with no extensions):
\eqn{a + b}: inline equation
\deqn{a + b}: display (block) equation
Tables are created with \tabular{}. It has two arguments:
Column alignment, specified by letter for each column (l = left, r = right, c = centre.)
Table contents, with columns separated by \tab and rows by \cr.
The following function turns an R data frame into the correct format, adding a row consisting of the (bolded) column names and prepending each row with #' for pasting directly into the documentation.
tabular <- function(df, ...) {
stopifnot(is.data.frame(df))
align <- function(x) if (is.numeric(x)) "r" else "l"
col_align <- purrr::map_chr(df, align)
cols <- lapply(df, format, ...)
contents <- do.call("paste",
c(cols, list(sep = " \\tab ", collapse = "\\cr\n#' ")))
paste("#' \\tabular{", paste(col_align, collapse = ""), "}{\n#' ",
paste0("\\strong{", names(df), "}", sep = "", collapse = " \\tab "), " \\cr\n#' ",
contents, "\n#' }\n", sep = "")
}
cat(tabular(mtcars[1:5, 1:5]))
#> #' \tabular{rrrrr}{
#> #' \strong{mpg} \tab \strong{cyl} \tab \strong{disp} \tab \strong{hp} \tab \strong{drat} \cr
#> #' 21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
#> #' 21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
#> #' 22.8 \tab 4 \tab 108 \tab 93 \tab 3.85\cr
#> #' 21.4 \tab 6 \tab 258 \tab 110 \tab 3.08\cr
#> #' 18.7 \tab 8 \tab 360 \tab 175 \tab 3.15
#> #' }