Search code examples
rroxygen2

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

e.g. 

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

Solution

  • 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, e.g. in the vignette