如何使用roxygen2运行示例？

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()

Do check it yourself before judging. :)

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.