Writing with roxygen2

roxygen2 (opens new window) is a package created by Hadley Wickham to facilitate documentation.

It allows to include the documentation inside the R script, in lines starting by #'. The different parameters passed to the documentation start with an @, for example the creator of a package will by written as follow:

#' @author The Author

For example, if we wanted to document the following function:

mean<-function(x) sum(x)/length(x)

We will want to write a small description to this function, and explain the parameters with the following (each line will be explained and detailed after):

#' Mean
#'
#' A function to compute the mean of a vector
#' @param x A numeric vector
#' @keyword mean
#' @importFrom base sum
#' @export
#' @examples
#' mean(1:3)
#' \dontrun{ mean(1:1e99) }
mean<-function(x) sum(x)/length(x)

• The first line #' Mean is the title of the documentation, the following lines make the corpus.
• Each parameter of a function must be detailed through a relevant @param. @export indicated that this function name should be exported, and thus can be called when the package is loaded.
• @keyword provides relevant keywords when looking for help
• @importFrom lists all functions to import from a package that will be used in this function or in you package. Note that importing the complete namespace of a package can be done with @import
• The examples are then written below the @example tag.
• The first one will be evaluated when the package is built;
• The second one will not - usually to prevent long computations - due to the \dontrun command.

Building the documentation

The documentation can be created using devtools::document(). Note also that devtools::check() will automatically create a documentation and will report missing arguments in the documentation of functions as warnings.

Parameters