R 帮助页面中的“未运行”是什么意思？答案

【问题标题】：What does "not run" mean in R help pages?R 帮助页面中的“未运行”是什么意思？
【发布时间】：2010-11-30 01:34:44
【问题描述】：

有时在 R 帮助页面上，短语“not run”会出现在 cmets 中。从“with()”的帮助页面查看这个：

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**)

示例代码中的“未运行”是什么意思？

【问题讨论】：

只是一个相关的提示。您可以通过发出“example(glm)”来运行示例代码。
这是一个很好的提示。而且我敢打赌，绝大多数 R 用户都没有意识到这一点。
但请注意 example(fn) 仍然不会包含在 dontRun 中的示例代码
除非您将run.dontrun 参数设置为TRUE

标签： r

【解决方案1】：

“未运行”包含不应在 example 函数中执行的代码（例如耗时的代码部分、用户交互......）。

参见例如?example:

如手册 Writing R Extensions 中所述，作者帮助页面可以为两个异常标记部分示例规则

'dontrun' 包含不应运行的代码。
'dontshow' 包含在帮助页面上不可见的代码，但会由包检查工具和 'example()' 函数。这以前是“testonly”，并且该表格仍然被接受。

【讨论】：

...我怎么不知道这个功能？
这不仅仅是通常放在 \dontrun{} 中的耗时代码。需要用户输入的代码也需要在 dontrun 中，否则它不会通过R CMD check
或者：依赖于可能未安装在用户机器上的包的代码。使用 \dontrun{} 有很多很多很多的理由

【解决方案2】：

在"Writing R Extensions" 手册中，关于 \examples{...} 的部分中说

您可以将 \dontrun{} 用于只应显示但不运行的文本，将 \dontshow{} 用于不应该向用户显示但将由 example() 运行的额外测试命令

当您构建一个包时，\dontrun{} 闭包中的所有代码都会在帮助中显示为

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

编辑：This answer 更早。

【讨论】：

【解决方案3】：

这增加了\donttest{}，并（逐字）取自@hadley 的R Packages。

但是，为了便于说明，包含导致错误的代码通常很有用。 \dontrun{} 允许您在示例中包含从未使用过的代码。还有另外两个特殊命令。 \dontshow{} 已运行，但未显示在帮助页面中：这对于非正式测试很有用。 \donttest{} 在示例中运行，但在 R CMD 检查中不会自动运行。如果您有需要很长时间运行的示例，这将很有用。选项总结如下。

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

【讨论】：

注意 donttest 现在已经测试了
对于包提交，您是否必须在 .Rd 中有任何额外的 cmets 证明省略代码块？由于 \donttest{} 示例，我进行了包失败检查，我想知道它是否像将其更改为 \dontrun{} 一样简单。该函数用于从 ftp 下载数据，CRAN 注释为：“.Rd 文件中未对此进行注释。请注意 example() 将运行这些部分”。
是的，应该就是这么简单。
@TylerRinker 您的意思是该功能已被验证为工作，或者 @donttest{ } 中的代码现在由 CRAN 在进行检查时运行？
是的，这里引用了 Hadley 书中的一段话：“出于说明的目的，包含导致错误的代码通常很有用。\dontrun{} 允许您在示例中包含以下代码：不运行。（您曾经可以将 \donttest{} 用于类似目的，但不再推荐，因为它实际上已经过测试。）"

【解决方案4】：

Friedrich Leisch 的必读Creating R Packages: A Tutorial 第 5.4 章（R 文档文件）中的 C 和 p：

示例部分应包含可执行的 R 代码，并自动运行代码是检查的一部分一袋。有两个特别的示例的标记命令：

dontrun：\dontrun{} 内的所有内容不被测试执行或例子（）。这很有用，例如，对于交互功能，函数访问互联网等。不要滥用它让你的生活更轻松通过举出不可能的例子执行。

【讨论】：

【解决方案5】：

此处的规范示例可能在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)

如果这样运行，它当然会产生不良影响。

【讨论】：