use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a function

[rossellhayes]

use_package_doc() leads to an R-CMD-CHECK warning if the package contains an exported function with the same name as the package itself.

From my package ipa, which exports the function ipa():

checking Rd metadata ... WARNING
##[warning]Rd files with duplicated alias 'ipa':
  ‘ipa-package.Rd’ ‘ipa.Rd’

Is it possible to make package documentation still accessible from package?foo and ?`foo-package` even if ?foo is already used by function documentation?

[jennybc]

I know I've wrestled with this problem in reprex and it seems like I figured it out?

https://github.com/tidyverse/reprex/blob/master/R/reprex-package.R

https://github.com/tidyverse/reprex/blob/master/R/reprex.R

I'm not going to look any further into this atm because I'm working on other parts of usethis. But if someone wants to do some analysis in this thread, that's welcome.

I think this is semi-rare, so I don't think I would merge a PR if we have to take on a lot of extra code or complexity to handle this case.

[rossellhayes]

I think the example usage from reprex is very helpful. I'll adopt that method in my packages!

[hadley]

I'm pretty sure the key is to set @aliases so that roxygen2 doesn't automatically add both {pkg} and {pkg}-package. However, detecting this case is going to be a little bit tricky — you'll either need to temporarily install or load the package.

[hadley]

Lets fix this in roxygen2: r-lib/roxygen2#1160

[SimonDedman]

Hi folks, notwithstanding there's a desire to fix this in roxygen2 at some point, until said point, would it be possible to add Jenny's reprex, simply the following block by way of example:

#' @keywords internal
#' @aliases reprex-package
"_PACKAGE"

to the Aliases section of Roxygen2 docs, as well as a note in usethis::use_package_doc, since that's the likely point from which most users will bump into this problem? It's an easy fix (for the user) but something of a pain to hunt it down (I asked in vain on SO). Thanks in advance.

[jennybc]

I'd be happy to review a PR with a concise addition to the docs for use_package_doc().

[SimonDedman]

use_package_doc() function is in documentation.R script (with 2 other similarly-named functions). However use_package_doc's Arguments are in template.R. template.R has an examples section but those examples don't appear in use_package_doc. On reflection, this shouldn't be an example, since it's not an example of how to use use_package_doc(). I've therefore placed suggested lines as @details in documentation.R. (I then tried to do it as an example since it'd be in code format but I couldn't for the life of me get it to display).

I will now attempt my first pull request, fully anticipating spectacular failure.