How do I resolve Rd warning "missing file link" when building packages in RStudio?

Question

After building a simple test package to isolate this issue, I receive the following warning when I run 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)

The issue occurs when you link to functions that point to an Rd file of a different name. For example, in my simpleTest package, the documentation links to both dplyr::mutate() and dplyr::transmute(), both of which are documented in the mutate.Rd file. The former link does not cause the Rd warning, while the latter does. However, both links work when you look at the help page for the current package.

The .R file for the simpleTest package is included below. I run devtools::document() and then build the package in a skeleton package directory.

---

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

This is because the links are created based on the names of the files, not the aliases. If you just use \link{foo}, foo is a topic (and hence you can use aliases without problem). The moment however you use any of the forms :

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

foo needs to be a file and hence you can only use the name and not the alias. If you check ?dplyr::mutate, you see that mutate is the name (upper left corner) and transmute is an alias. So when you try to use the alias the link will (likely) work, but you will see the warning you saw.

To avoid that, you need :

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

For reference: https://cran.r-project.org/doc/manuals/R-exts.html#Cross_002dreferences