在 RStudio 中构建包时如何解决 Rd 警告“缺少文件链接”？

Question

在构建一个简单的测试包来隔离这个问题后，我在运行Rcmd.exe INSTALL --nomultiarch --with-keep.source simpleTest 时收到以下警告：

* installing to library 'C:/Users/user/Documents/R-dev'
* installing *source* package 'simpleTest' ...
** R
** preparing package for lazy loading
** help
*** installing help indices
  converting help for package 'simpleTest'
    finding HTML links ...    hello                                   html  
Rd warning: C:/user/RPackages/simpleTest/man/hello.Rd:11: missing file link 'transmute'
 done
** building package indices
** testing if installed package can be loaded
* DONE (simpleTest)

当您链接到指向不同名称的 Rd 文件的函数时，会出现此问题。例如，在我的 simpleTest 包中，文档链接到 dplyr::mutate() 和 dplyr::transmute()，两者都记录在 mutate.Rd 文件中。前一个链接不会导致 Rd 警告，而后者会。但是，当您查看当前软件包的帮助页面时，这两个链接都有效。

simpleTest 包的 .R 文件包含在下面。我运行devtools::document()，然后在骨架包目录中构建包。

---

你好.R

#' print hello
#'
#' This does something less complicated than \code{\link[dplyr:mutate]{dplyr::mutate()}} 
#' and \code{\link[dplyr:transmute]{dplyr::transmute()}}.

#' @export
hello <- function() {
  print("Hello, world!")
}

Answer 1

这是因为链接是根据文件名而不是别名创建的。如果你只使用\link{foo}，foo 是一个主题（因此你可以毫无问题地使用别名）。但是，您使用任何形式的那一刻：

\link[pkg]{foo}
\link[pkg:foo]{bar}

foo 需要是一个文件，因此您只能使用名称而不是别名。如果您检查?dplyr::mutate，您会看到mutate 是名称（左上角），transmute 是别名。因此，当您尝试使用别名时，该链接（可能）会起作用，但您会看到您看到的警告。

为避免这种情况，您需要：

\link[dplyr:mutate]{dplyr::transmute()}

供参考：https://cran.r-project.org/doc/manuals/R-exts.html#Cross_002dreferences