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

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?

Thurmond

I think /inst/ moves to / when installing the package? I guess this won't matter though if the documentation is already built? – Thurmond

Yes inst/examples should move to examples and I would think you could then reference /examples in your documentation. – Eurus

OK inst/examples works well. I can reference /inst/examples/file.R in the source code, then create documentation with devtools::document(). /inst/examples moves to /examples, but I think this is irrelevant as the documentation is already built... – Thurmond

I can't decide if this is a good idea or not. It makes it a bit easier to run your examples, but isn't the whole point of roxygen that you keep the documentation right next to where the function is defined? – Maurizio

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

Segregation

I find it useful when I have many lines for the examples with indentation that I want to preserve. Most of the time I still use @examples though. – Thurmond