Wie kann ich kein Beispiel mit roxygen2 ausführen?

91

Ich schreibe gerade eine Geokodierungsfunktion , die auf einem Bing Maps-Schlüssel beruht. Natürlich möchte ich meine lieber nicht veröffentlichen, und die Beispiele scheitern ohne eine.

Wie füge ich ein Beispiel hinzu, das Benutzer manuell ausführen können, aber währenddessen nicht ausführen lassen R CMD check?

Ari B. Friedman
quelle

Antworten:

144

Verwenden \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)
#'}
GSee
quelle
2
Dies ist dokumentiert in ?exampleund Schreiben von R-Erweiterungen
GSee
2
@Jeroen, ich glaube, roxygen2das hat das @exampleTag gemacht, also denke ich, dass es ein roxygen2Problem ist. Ich denke nicht, dass \example{}es gültig ist - siehe cran.r-project.org/doc/manuals/…
GSee
2
Nach dem Titel des Themas zu urteilen, geht es um die roxygen2-Syntax und nicht um die .Rd-Syntax?
Jeroen
Danke für die Antwort. Es hat bei mir zuerst nicht funktioniert, weil ich @examplestattdessen verwendet habe @examples. Beide Tags werden in RStudio automatisch vervollständigt. Ich bin jetzt glücklich.
Paul Rougieux
5
Ich denke, die richtige Antwort für das, wonach gefragt wird, ist nicht testen und nicht dontrun. Siehe? Beispiel und stackoverflow.com/questions/12038160/… . Siehe auch cran.r-project.org/web/packages/roxygen2/vignettes/rd.html .
Julian Karls
32

Sie können \donttest{}zu Ihrem Beispiel verwenden. Das Snippet wird in Ihrer Dokumentation bereitgestellt, jedoch nicht mit dem R CMD Check getestet.

Für weitere Informationen -> ?example

#' @example
\donttest{
    2^2
    }

Diese 2 ^ 2 werden nicht ausgeführt, wenn Sie ausgeführt werden devtools::check()

Überprüfen Sie es selbst, bevor Sie urteilen. :) :)

samkart
quelle
13
Es scheint, dass dies die akzeptierte Antwort sein sollte, anstatt Dontrun. Beispiel: "donttest enthält Code, der normalerweise ausgeführt werden sollte, jedoch nicht während der Paketprüfung." in der Erwägung, dass "dontrun Code enthält, der nicht ausgeführt werden sollte". Ich habe auch einen Kommentar von Cran-Betreuern erhalten, um von Dontrun zu Donttest zu wechseln.
Julian Karls
3
Stimme voll und ganz @JulianKarls zu. Ich habe das gleiche Feedback von CRAN-Betreuern erhalten.
David
9

Für diejenigen, die @example path/to/example.Ranstelle des @examplesTags verwenden, können Sie die \dontrunUmgebung direkt in der example.RDatei verwenden. Beispielsweise

# 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
Peter
quelle
1
Dies funktioniert nicht für mich (läuft unter Win 10, 64 Bit, R Version 3.5.0)
JBJ
2

Ari, ich benutze auch roxygen2 (Version 4.1.0). Das Folgende ist das Ende meines roxygen2-Markups in meiner Funktionsdefinition (gctemplate) bis zum Beginn des Realteils.

#' @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){
...

Ich kenne die Dontrun-Methode von GSee.
In meiner Technik sind das numerische Beispiel und der Text, der das numerische Beispiel erklärt, beide Kommentare. Ich benutze Einrückungen, um zwischen diesen beiden zu unterscheiden. Beachten Sie, dass nach "# '" jeweils 1 scharfe und 2 scharfe Punkte angezeigt werden. Ich verwende in meinen Paketen immer die obige "# '## / #' #" Technik. Der Benutzer kann kopieren und einfügen, wann immer er die Funktion testen möchte. Diese Technik ist meiner Meinung nach eher parallel zum klassischen Kommentarbombardement der Software-Codierungsphilosophie.

Erdogan CEVHER
quelle
13
Wenn Sie verwenden dontrun{}, kann der Benutzer aufrufen example(myFunction, run.dontrun=TRUE), während Sie, wenn Sie die Beispiele einfach auskommentieren, keine andere Möglichkeit haben, die Beispiele auszuführen, als sie zu kopieren / einzufügen.
GSee