wannymahoots wannymahoots - 1 month ago 5
R Question

Location of files when using @example tag with roxygen2

When documenting a function with roxygen2 it is possible to place examples in a separate file.

See here: http://r-pkgs.had.co.nz/man.html
"Instead of including examples directly in the documentation, you can put them in separate files and use @example path/relative/to/packge/root to insert them into the documentation."

and here: http://roxygen.org/roxygen2-manual.pdf


#' Add together two numbers.
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @example /path/to/example/add.R
add <- function(x, y) {
x + y

My question is: what path should be used to store the example R files?


The appropriate location for examples used in your roxygen is:


The roxygen line then should be:

#' @example /inst/examples/add.R

Is this good practice? I think it is, since:

  • It makes it easier to run, modify and test the examples whilst developing
  • It makes it possible (in principle, at least) to re-use the examples in different places in the documentation, e.g. in the vignette