Location of files when using @example tag with roxygen2

Question

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

eg

#' 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?

Answer 1

The appropriate location for examples used in your roxygen is:

inst/examples/

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, eg in the vignette