How to not run an example using roxygen2? - r

Question

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?

Answer 1

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

Answer 2

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.

Answer 3

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

Answer 4

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.

Answer 5

\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