R Language roxygen2 Documenting a package with roxygen2
Example
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
#' Meanis the title of the documentation, the following lines make the corpus. - Each parameter of a function must be detailed through a relevant
@param.@exportindicated that this function name should be exported, and thus can be called when the package is loaded. @keywordprovides relevant keywords when looking for help@importFromlists 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
@exampletag.- The first one will be evaluated when the package is built;
- The second one will not - usually to prevent long computations - due to the
\dontruncommand.
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.
