How to Not Run an Example Using Roxygen2

How to not run an example using roxygen2?

Use \dontrun{}

#'@examples
#'\dontrun{
#'geocode("3817 Spruce St, Philadelphia, PA 19104")
#'geocode("Philadelphia, PA")
#'dat <- data.frame(value=runif(3),address=c("3817 Spruce St, Philadelphia, PA 19104","Philadelphia, PA","Neverneverland"))
#'geocode(dat)
#'}

Avoid checking \notrun examples when using R CMD check

Sometimes when you change documentation, such as examples, the old files remain in the man folder of your package. This is why after a change such as wrapping examples in \dontrun{}, it can make sense to clean up the directory. You can do so with roxygen2 by running:

roxygen2::roxygenise(clean = TRUE)

R package: demonstrate a failing example

You can add it within a \dontrun{} block so that it does not cause errors.
http://r-pkgs.had.co.nz/man.html#man-functions

ignore script with roxygen2

For new visitors, this is not code within roxygen documentation for a function; for that, it would be best to surround it with \donotrun, as in

#' @examples
#' \donotrun{
#' something_goes_here()
#' }
myfunction <- function(...) {

In this case, though, it's including some files in the package itself.

1. Files you place within the ./inst/ directory are installed with the packages, but they are not assumed to be R scripts (or anything, for that matter). The authoritative reference for this starts with "Writing R Extensions", Section 1.1.5 Package sub-directories. This will install the file(s) on each computer that installs the package via install.packages(...).

2. If you want something within the package source but not to be installed with the package itself, I suggest you place a file in the root of the package named .Rbuildignore (ref: same link, now section 1.3.2 Building package tarballs). Files that are matched by these patterns will not be included in the package tarball. Whether you put the actual file within ./inst/ or anywhere else is completely up to you: if it is in the .Rbuildignore file, then it will be excluded from the tarball (and therefore seen/findable by the end users).

R Package Doc (roxygen2) - example part - execute example

The code in the @examples section is meant to be executed as written, and in fact it is run every time you check the package with R CMD check ("Check Package" in R Studio). Therefore, it must not contain the output from those commands.

However, as @SymbolixAU writes, you can add comments, e.g.:

#' Add together two numbers.
#' 
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' # 2
#'
#' add(10, 1)
#' # 11
#' @export
add <- function(x, y) {
  x + y
}

Or maybe rather:

#' Add together two numbers.
#' 
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1) # returns 2
#'
#' add(10, 1) # returns 11
#' @export
add <- function(x, y) {
  x + y
}

How do you escape } using roxygen2?

TLDR: longer term fix: file an issue.

You "got lucky" this built since you had just enough }'s to get past some Rd installation errors.

I even tried using @example inst/examples/ex.r and putting the code (with the \dontrun{} wrapper since it is supported there) and the same thing happens with that method since the same roxygen parsing/translating code seems to be in play there too.

• SHORT TERM FIX #1: manually edit the generated Rd file to do the single \} for each of the }. To make this something you don't accidentally overwrite, generate it once, do the fix then de-roxygenize that function until there's a fix.

• SHORT TERM FIX #2: for that bit of code, the string assignment can happen outside of the \dontrun{} block (which is really what's causing this). Move it out and you can continue with roxygenizing.

• LONG TERM FIX: file an issue to the above URL.

---

Related Topics