对于使用Roxygene的示例，当使用@includemd时，R CMD检查会发出警告

Question

我正在使用roxygen2编写一个R包作为文档。我使用@includeRmd标签来减少重复，这可以很好地在帮助文件、小插曲和pkgdown网站上生成一致的文档。

我唯一的问题是，当我使用标签插入示例时，R CMD check会给我一个严重的警告。这是我的设置：

---

R/adder.R。。。roxygen2块功能的源代码

#' Add three numbers
#'
#' @includeRmd includes/adder_description.Rmd description
#'
#' @param x First number to add
#' @param y Second number to add
#' @param z Third number to add
#' @return The sum of the numbers
#'
#' @includeRmd includes/adder_examples.Rmd examples
#'
#' @md
#' @export
adder <- function(x, y, z) {
x+y+z
}

includes/adder_description.Rmd。。。中包含的描述文本

The `adder()` function adds three numbers.

includes/adder_examples.Rmd。。。要包括的示例代码

```{r adder_examples}
adder(3,5,6)
``` 

---

在我的小插曲和README中，我可以插入相同的描述文本和示例代码，如下所示：

```{r child=rprojroot::find_package_root_file("includes", "adder_description.Rmd")}
```
```{r child=rprojroot::find_package_root_file("includes", "adder_examples.Rmd")}
```

一切都很好：描述文本和示例代码被一致地包含在所有内容中。但是，R CMD check对roxygen2在man/adder.Rd中生成的examples{}块发出以下警告：

> checking Rd files ... WARNING
checkRd: (7) adder.Rd:23: Tag if is invalid in a examples block
checkRd: (7) adder.Rd:23-24: Tag preformatted is invalid in a examples block
checkRd: (7) adder.Rd:24: Tag if is invalid in a examples block
checkRd: (7) adder.Rd:24-25: Tag preformatted is invalid in a examples block

查看.Rd文件，当我以正常方式包含示例时，肯定会出现一些不寻常的标记。

我的问题是：发出这些警告是因为我错误地使用了@includeRmd标记，还是这个用例不是标记的用途？看来，这些警告将阻止向CRAN提交包裹。

Answer 1

似乎不支持您使用@includeRmd标记。您可以使用它生成"详细信息"的"说明"或(子(部分，但不能生成"示例"。文件说明：

当前无法在外部Rmd文档中记录函数参数、返回值等。

这并不太令人惊讶，原因有几个：

• R CMD check希望examples{}块包含逐字记录的R代码，而不是Markdown，因此在没有预处理的情况下将Markdown注入块注定会失败。由于区块页眉和页脚，以下是无效的R代码：

  ```{r adder_examples}
  adder(3, 5, 6)
  ```
  

  也就是说，roxygen2似乎做了一些预处理，因为上面生成了以下examples{}块：

  examples{
  if{html}{out{<div class="sourceCode r">}}preformatted{adder(3, 5, 6)
  }if{html}{out{</div>}}preformatted{## [1] 14
  }
  

  注入的文本在description{}或details{}内部有效，但在examples{}内部无效，因为它不是逐字逐句的R代码。

• 作为"；逐字逐句地"；规则，examples{}块允许dontrun、dontshow和donttest宏。它们由R CMD check异常处理，但不是由knitr渐晕引擎处理。如果你试图将这个区块插入到一个小插曲中，你会遇到构建失败：

  ```{r adder_examples}
  adder(3, 5, 6)
  dontrun{
  adder(3, 5, "6")
  }
  ```
  

  对于块选项eval = 1L，解析器仍然抛出一个错误。(eval = FALSE看起来还可以，但第一行没有求值。(因此，即使如果@includeRmd可以用于生成有效的examples{}块，您也不一定能够与渐晕图共享代码。

如果您真的想要外部化您的Examples，那么您可以尝试用老式的方式来做，即使用shell脚本和sed，使用@examples作为文本插入的标记(这里有一些示例(。我怀疑复杂性是否值得，但你可以成为评判者。。。

---

更新：我刚刚尝试用我自己的最小包破解一些东西。。。

pkgname <- "foo"
usethis::create_package(pkgname, rstudio = FALSE, open = FALSE)
setwd(pkgname)
usethis::use_directory(file.path("inst", "examples"))
text <- "
#' @title A title
#' @description A description.
#' @param a,b Arguments.
#' @includeRmd inst/examples/add.Rmd examples
#' @export
add <- function(a, b) a + b
"
cat(text, file = file.path("R", "add.R"))
text <- "
add(1, 1)
"
cat(text, file = file.path("inst", "examples", "add.Rmd"))
roxygen2::roxygenize(".")
writeLines(readLines(file.path("man", "add.Rd")))

examples{
add(1, 1)
}

因此，看起来类似于删除块头和块尾可以允许roxygen2生成一个合理的examples{}块。但我错了：

text <- "
add(1, 1)
add(2, 2)
"
cat(text, file = file.path("inst", "examples", "add.Rmd"))
roxygen2::roxygenize(".")
x <- readLines(file.path("man", "add.Rd"))
writeLines(tail(x, -(grep("^\\examples", x) - 1L)))

examples{
add(1, 1) add(2, 2)
}

当示例跨越两行或更多行时，生成的文本是无效的R代码，因为Markdown将换行视为空格。