Como não executar um exemplo usando roxygen2?


91

Estou escrevendo uma função de geocodificação agora que depende de ter uma chave do Bing Maps. Obviamente, prefiro não publicar o meu, e os exemplos falham sem um.

Como posso incluir um exemplo para que os usuários executem manualmente, mas não executem durante R CMD check?

Respostas:


145

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

2
isto está documentado em ?examplee Escrevendo Extensões R
GSee

2
@Jeroen, acho que roxygen2foi isso que fez a @exampletag, então acho que é um roxygen2problema. Eu não acho que \example{}seja válido - veja cran.r-project.org/doc/manuals/…
GSee 01 de

2
A julgar pelo título do tópico, a questão é sobre a sintaxe roxygen2 e não sobre a sintaxe .Rd.
Jeroen

Obrigado pela resposta. Não funcionou para mim primeiro porque eu estava usando em @examplevez de @examples. Ambas as tags surgem no preenchimento automático do RStudio. Eu estou feliz agora.
Paul Rougieux de

5
Acho que a resposta correta para o que está sendo solicitado é não teste e não faça. Consulte? Example e stackoverflow.com/questions/12038160/… . Consulte também cran.r-project.org/web/packages/roxygen2/vignettes/rd.html .
Julian Karls

32

Você pode usar o \donttest{}seu exemplo. O snippet será fornecido em sua documentação, mas não será testado com o R CMD Check.

Para mais informações -> ?example

#' @example
\donttest{
    2^2
    }

Este 2 ^ 2 não será executado quando você correr devtools::check()

Verifique você mesmo antes de julgar. :)


13
Parece que essa deve ser a resposta aceita, em vez de dontrun. De? Exemplo 'donttest inclui o código que normalmente deve ser executado, mas não durante a verificação do pacote.' enquanto 'dontrun inclui código que não deve ser executado.' Eu também recebi um comentário dos mantenedores do cran para mudar de dontrun para donttest.
Julian Karls

3
Concordo totalmente com @JulianKarls. Recebi o mesmo feedback dos mantenedores do CRAN.
David

9

Para quem está usando no @example path/to/example.Rlugar da @examplestag pode-se usar o \dontrunambiente diretamente no example.Rarquivo. Por exemplo

# 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

1
isso não funciona para mim (executando em Win 10, 64 bits, R versão 3.5.0)
JBJ

2

Ari, também uso o roxygen2 (versão 4.1.0). A seguir está o fim da minha marcação roxygen2 na definição da minha função (gctemplate) até o início da parte real.

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

Eu conheço o método dontrun do GSee.
Na minha técnica, o exemplo numérico e o texto explicando o exemplo numérico são ambos comentários. Eu uso recuo para fazer a diferença entre os dois; Observe que há 1 sustenido e 2 sustenidos respectivamente após "# '". Eu sempre uso a técnica "# '## / #' #" acima em meus pacotes. O usuário pode executar a operação de copiar e colar sempre que quiser testar a função. Esta técnica é - a meu ver - mais paralela com o clássico bombardeio de comentários da filosofia de codificação de software.


13
Se você usar dontrun{}, o usuário poderá chamar example(myFunction, run.dontrun=TRUE), ao passo que, se você simplesmente comentar os exemplos, não terá como executar os exemplos a não ser copiar / colar.
GSee
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.