¿Qué significa "no ejecutar" en las páginas de ayuda de R?

A veces, en una página de ayuda de R, aparece la frase "no ejecutar" en los comentarios. Consulte esto en la página de ayuda para "con ()":

Examples
require(stats); require(graphics)
#examples from glm:
**## Not run:** 
library(MASS)
with(anorexia, {
    anorex.1 <- glm(Postwt ~ Prewt + Treat + offset(Prewt),
                    family = gaussian)
    summary(anorex.1)
})
## End(**Not run**)

¿Qué significa "no ejecutar" en el código de ejemplo?

"no ejecutar" incluye código que no debería ejecutarse en la examplefunción (por ejemplo, partes de código que consumen mucho tiempo, interacción del usuario, ...).

ver, por ejemplo ?example:

Como se detalla en el manual Writing R Extensions , el autor de la página de ayuda puede marcar partes de los ejemplos para dos reglas de excepción

• 'dontrun' incluye código que no debe ejecutarse.

• 'dontshow' encierra código que es invisible en las páginas de ayuda, pero que será ejecutado tanto por las herramientas de verificación de paquetes como por la función 'example ()'. Anteriormente, esto era 'testonly' y ese formulario todavía se acepta.

En el manual "Escritura de extensiones R" , en la sección sobre \ ejemplos {...} se dice que

Puede usar \ dontrun {} para texto que solo debe mostrarse, pero no ejecutarse, y \ dontshow {} para comandos adicionales para pruebas que no deben mostrarse a los usuarios, pero que se ejecutarán con un ejemplo ()

Cuando construyes un paquete, todo el código en el cierre de \ dontrun {} es visible en la ayuda como

## Not run:
...
## End(**Not run**)

editar: Esta respuesta fue anterior.

Esto agrega \donttest{}y está tomado (literalmente) de los paquetes R de @ hadley .

Sin embargo, con fines ilustrativos, suele ser útil incluir código que provoque un error. \dontrun{}le permite incluir código en el ejemplo que nunca se usa. Hay otros dos comandos especiales. \dontshow{}se ejecuta, pero no se muestra en la página de ayuda: esto puede ser útil para pruebas informales. \donttest{}se ejecuta en ejemplos, pero no se ejecuta automáticamente en R CMD check. Esto es útil si tiene ejemplos que tardan mucho en ejecutarse. Las opciones se resumen a continuación.

Command      example    help       R CMD check
\dontrun{}                 x
\dontshow{}       x                          x
\donttest{}       x        x

C & p del Capítulo 5.4 (Archivos de documentación de R) de MUST-TO-LEAD Creación de paquetes R: Un tutorial de Friedrich Leisch:

La sección de ejemplos debe contener código R ejecutable, y la ejecución automática del código es parte de la verificación de un paquete. Hay dos comandos de marcado especiales para los ejemplos:

dontrun : Todo lo que hay dentro de \ dontrun {} no es ejecutado por las pruebas o example (). Esto es útil, por ejemplo, para funciones interactivas, funciones de acceso a Internet, etc. No lo use incorrectamente para hacerle la vida más fácil dando ejemplos que no se pueden ejecutar.

El ejemplo canónico aquí podría estar en la página de ayuda para rm:

## Not run: 
## remove (almost) everything in the working environment.
## You will get no warning, so don't do this unless you are really sure.
rm(list = ls())

## End(Not run)

Si esto funcionara, por supuesto, tendría efectos no deseados.