What does “not run” mean in R help pages?

Question

Sometimes on an R help page the phrase \"not run\" appears in comments. Check out this from the help page for \"with()\":

Examples
require(stats); require(gr         


        

Answer 1

This adds \donttest{} and is taken (verbatim) from @hadley's R Packages.

However 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 never used. There are two other special commands. \dontshow{} is run, but not shown in the help page: this can be useful for informal tests. \donttest{} is run in examples, but not run automatically in R CMD check. This is useful if you have examples that take a long time to run. The options are summarised below.

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

Answer 2

C & p from Chapter 5.4 (R Documentation Files) of the MUST-TO-READ Creating R Packages: A Tutorial by Friedrich Leisch:

The examples section should contain executable R code, and automatically running the code is part of checking a package. There are two special markup commands for the examples:

dontrun: Everything inside \dontrun{} is not executed by the tests or example(). This is useful, e.g., for interactive functions, functions accessing the Internet etc.. Do not misuse it to make life easier for you by giving examples which cannot be executed.

Answer 3

In "Writing R Extensions" manual, in section about \examples{...} is said that

You can use \dontrun{} for text that should only be shown, but not run, and \dontshow{} for extra commands for testing that should not be shown to users, but will be run by example()

When you build a package then all code in \dontrun{} closure is visible in help as

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

edit: This answer was earlier.

Answer 4

"not run" encloses code that shouldn't be executed in the example function (e.g. time-consuming code parts, user-interaction, ...).

see e.g. ?example:

As detailed in the manual Writing R Extensions, the author of the help page can markup parts of the examples for two exception rules

• 'dontrun' encloses code that should not be run.

• 'dontshow' encloses code that is invisible on help pages, but will be run both by the package checking tools, and the 'example()' function. This was previously 'testonly', and that form is still accepted.

Answer 5

The canonical example here might be in the help page for 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)

If this ran it would of course have undesired effects.