How to not run an example using roxygen2?

I'm writing a geocoding function right now that relies on having a Bing Maps Key. Obviously I'd rather not publish mine, and the examples fail without one.

How do I include an example for users to run manually, but not have it executed during R CMD check?

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)
#'}

You can use \donttest{} to your example. The snippet will be provided in your documentation, but won't get tested with the R CMD Check.

For more info --> ?example

#' @example
\donttest{
    2^2
    }

This 2^2 won't get run when you run devtools::check()

---

EDIT

Per the latest release notes or NEWS for R 4.0.0, examples within \donttest{} will now be tested by default. This can, however, be overridden by setting environment variable _R_CHECK_DONTTEST_EXAMPLES_ to FALSE.

> R CMD check --as-cran now runs \donttest examples (which are run by example()) instead of instructing the tester to do so. This can be temporarily circumvented during development by setting environment variable R_CHECK_DONTTEST_EXAMPLES to a false value.

According to this GitHub issues discussion (credited here), Hadley Wickham noted that

> Generally, now if you don't want to run tests on CRAN \dontrun{} is more likely to work, but using \dontrun{} may cause initial submission to fail.

There are other ways as well that will let you continue to use donttest{}, refer the aforementioned discussions for the workarounds.

For those who are using @example path/to/example.R instead of the @examples tag you can use the \dontrun environment directly in the example.R file. For example

# example.R
\dontrun{
# this is a long running example
for(i in seq(1, 1e5)) { lm(mpg ~ wt, data = mtcars) }
}

# some other shorter example
2 + 2

Ari, I also use roxygen2 (version 4.1.0). The following is the end of my roxygen2 mark-up in my function (gctemplate) definition till the beginning of the real part.

#' @examples
#' ## List all G-causalities in a VAR system of 5 variables that will be searched in the pattern of 1 
#' ## causer (like-independent) variable and 2 like-dependents conditional on 5-(1+2)=2 of the remaining 
#' ## variable(s) in the system. Variables are assigned to numbers 1 to nvars. 
#' ## "1 2 5 3 4" in the resulting line of gctemplate is to indicate the 
#' ## (conditonal, partial, etc.) G-causality from variable 1 to variables 2 and 5 
#' ## conditonal on variables 3 and 4.
#' # gctemplate(5,1,2)
#' ## The number of all G-causalities to be searched in the above pattern.
#' #dim(gctemplate(5,1,2))[[1]]
#' @importFrom combinat combn
#' @export
gctemplate <- function(nvars, ncausers, ndependents){
...

I know GSee's dontrun method.
In my technique, the numerical example and the text explaining the numerical example are both comments. I use indentation to make difference between these two; Notice there are 1 sharp and 2 sharps respectively after "#'". I always use the above "#' ## / #' #" technique in my packages. The user is left to copy-paste operation whenever s/he wanna test the function. This technique is - according to me - more parallel with the classical comment bombardment of the software coding philosophy.

\dontrun{}

Is the correct function. See here:

>For the purpose of illustration, it’s often useful to include code that causes an error. \dontrun{} allows you to include code in the example that is not run. (You used to be able to use \donttest{} for a similar purpose, but it’s no longer recommended because it actually is tested.)

Source: https://r-pkgs.org/man.html?q=donttest#man-functions