roxygen2 v5.0.1

0

Monthly downloads

0th

Percentile

by Hadley Wickham

In-Source Documentation for R

A 'Doxygen'-like in-source documentation system for Rd, collation, and 'NAMESPACE' files.

Readme

roxygen2

Build Status CRAN_Status_Badge Coverage Status

all' hileth', Hephaiste; didou d'areten te kai olbon.* --Homer, 7th century BCE

Why use roxygen2?

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 from the stringr package:

#' The length of a string (in characters).
#'
#' @param string input character vector
#' @return numeric vector giving number of characters in each element of the
#'   character vector.  Missing strings have missing length.
#' @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
}

When you roxygenise your package these comments will be automatically transformed to the Rd file you need to pass R CMD check:

\name{str_length}
\alias{str_length}
\title{The length of a string (in characters).}
\usage{str_length(string)}
\arguments{
  \item{string}{input character vector}
}
\description{
The length of a string (in characters).
}
\seealso{\code{\link{nchar}} which this function wraps}
\value{
  numeric vector giving number of characters in each element of the
  character vector.  Missings string have missing length.
}
\examples{
str_length(letters)
str_length(c("i", "like", "programming", NA))
}

Installation

To get the current released version from CRAN:

install.packages("roxygen2")

To get the current development version from github:

# install.packages("devtools")
devtools::install_github("klutometis/roxygen")

Running

Roxygen does a live analysis of your source code: it loads all the code in your package, so it can create documentation using values in an R environment, not just source code. However, simulating package loading is rather tricky to do in general, so there are two ways to do it with roxygen:

  • roxygen2::roxygenise() just sources all files in the R/ directory

  • devtools::document() sources all files in the R/ directory, compiles source code in the src/ directory, loads data in the data/ directory and generally does an accurate job of simulating package loading.

If you have a simple package, you can use roxygenise(), but for anything more complicated, I recommend that you use document().

Roclets

roxygen2 comes with four roclets, tools for parsing your source code and producing files useful for documenting your package:

  • collate_roclet: allows you to add @include directives to ensure that files are loaded in the order they are needed

  • namespace_roclet: creates your NAMESPACE automatically. 95% of the time all you need to do is label functions, methods and classes that you want to export with the @export tag

  • rd_roclet: produces Rd files by inspecting both function definitions and roxygen2 comments in the source code

  • vignette_roclet: builds vignettes using tools::buildVignette().

By default, roxygenise will run the first three, but you can choose which ones to run using the roclet parameter, or field Roxygen in your DESCRIPTION:

Roxygen: list(roclets = c("rd", "collate"))

  • Hail, Hephaistos! Grant skill and weal.

Functions in roxygen2

Name Description
roc_proc_text Process roclet on string and capture results.
rd_roclet Roclet: make Rd files.
register.preref.parser Register tag parsers.
is_s3_generic Determine if a function is an S3 generic or S3 method.
update_collate Update Collate field in DESCRIPTION.
vignette_roclet Re-build outdated vignettes.
default_data_format Default format for data
source_package Source all files in a package.
object Constructors for S3 object to represent R objects.
namespace_roclet Roclet: make NAMESPACE.
new_roclet Build new roclet object.
roxygenize Process a package with the Rd, namespace and collate roclets.
load_options Load options from DESCRIPTION.
roxygen2-package In-Source Documentation for R
No Results!

Last month downloads

Details

URL https://github.com/klutometis/roxygen
License GPL (>= 2)
VignetteBuilder knitr
LinkingTo Rcpp
Collate 'RcppExports.R' 'alias.R' 'default-data-format.R' 'description.R' 'family.R' 'inherit-params.R' 'minidesc.R' 'object-defaults.R' 'object-from-call.R' 'object.R' 'order-params.R' 'parse-preref.R' 'parse.R' 'rc.R' 'rd-escape.R' 'rd-file-api.R' 'rd-parse.R' 'rd-tag-api.R' 'tag-registry.R' 'roclet-collate.R' 'roclet-namespace.R' 'roclet-rd.R' 'roclet-vignette.R' 'roclet.R' 'roxygen-tag.R' 'roxygen.R' 'roxygenize.R' 's3.R' 'safety.R' 'source.R' 'template.R' 'topic-name.R' 'topo-sort.R' 'usage.R' 'util-locale.R' 'utils.R'
RoxygenNote 5.0.1

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/roxygen2)](http://www.rdocumentation.org/packages/roxygen2)