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.
#' 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
}
@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 |
@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
|
@section <name>:
|
Provide a custom section with the name |
In addition, you can use @keywords internal to ensure
that documentation for a particular function is generated, but not added to the package
index.
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.
#' Package Name #' #' Package description. #' #' @docType package #' @name <package-name> #' @import assertthat #' @importFrom utils head tail #' @useDynLib <package-name> NULL
@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. |
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
For example, use |
\url{URL}
\href{URL}{text}
|
Link to content on the internet; for example, external documentation.
Use |
\enumerate{<items...>}
\itemize{<items...>}
\describe{<items...>}
|
Provide a list of items. \enumerate{
\item Item 1.
\item Item 2.
\item Item 3.
}
\describe{
\item{label-1}{text-1}
\item{label-2}{text-2}
}
|
\tabular{alignment}{text}
|
Provide a table of text.
Separate fields with \tabular{rl}{
Entry 1 \tab Entry 2 \cr
Entry 3 \tab Entry 4 \cr
}
|
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).