R Language roxygen2


authorAuthor of the package
examplesThe following lines will be examples on how to use the documented function
exportTo export the function - i.e. make it callable by users of the package
importPackage(s) namespace(s) to import
importFromFunctions to import from the package (first name of the list)
paramParameter of the function to document

Documenting a package with roxygen2

Writing with roxygen2

roxygen2 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.