roxygen2 is a Doxygen-like in-source documentation system for Rd, collation, and NAMESPACE. Its primary use is in documenting R functions in-line with the function definition.
roxygen2 is a doxygen-like documentation system for r packages; allowing in-source specification of Rd files, collation and namespace directives.
The standard way to write R documentation is to create Rd files (R documentation) in the man directory of a package. Rd files are a special file format which closely resembles latex. They can be processed into a variety of formats, including LaTeX, html and plain text.
These files describe each object (function, data set, class, generic or method).
With roxygen2, the documentation is written in comments next to each function. Then an R script is used to create the main files.
Example
#' The length of a string (in characters).
#'
#' @inheritParams str_detect
#' @return numeric vector giving number of characters in each element of the
#' character vector. Missing string have missing length.
#' @keywords character
#' @seealso \code{\link{nchar}} which this function wraps
#' @export
#' @examples
#' str_length(letters)
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
string <- check_string(string)
nc <- nchar(string, allowNA = TRUE)
is.na(nc) <- is.na(string)
nc
}
Advantages of roxygen2:
Code and documentation are adjacent
roxygen2dynamically inspects the objects. For example, it can automatically add links to super and subclasses.it takes care of other files that are fiddly or downright painful to maintain by hand: the namespace, collate order in description, and the demos index.
it abstracts over the differences in documenting r-s3 and s4 methods, generics and classes so that they behave basically the same.
The Rd2roxygen package provides a convenient way of converting
Rd files to roxygen comments for existing Rd files.
Repositories
Vignettes
- Controlling collation order
- Text formatting
- Managing your NAMESPACE
- Generating Rd files
- Rd keywords
- Getting started with Roxygen2
Other resources
- Writing Package Documentation by Josh Paulson
- The Object Documentation chapter of R Packages by Hadley Wickham
- Crantastic page
- Posts on R-bloggers
Related tags
- doxygen
- r's devtools package
- documentation and man
