What does "not run" mean in R help pages?

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

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.


"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.


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.

Tags:

R