File locations when using the @example tag with roxygen2

Question

When documenting functions with roxygen2, you can place the 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 the path @ example / 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: which path should be used to store example R files?

Answer 1

The appropriate place for the examples used in your roxygen is:

 inst/examples/ 

The roxygen string should be:

 #' @example inst/examples/add.R 

---

Is this a good practice? I think it is, because:

• This makes it easy to run, modify, and test development examples.
• This allows you (in principle, at least) to reuse examples in different places in the documentation, for example. in vignette