[R-pkg-devel] possible solution to package-documentation-alias problem

[Thomas Rusch]

Dear list,

I'd like to add that it looks like if the package has the same name as a 
function in the package, the default aliasing using the "_PACKAGE" 
sentinel will create two aliases of the same name in different .Rd files 
and R CMD check --as-cran will complain,

E.g. using roxygen

#'@keywords internal

"_PACKAGE"

in a file foo-package.R if there also is a foo.R documented with 
roxygen, it creates foo-package.Rd with \alias{foo} and there will also 
be a file foo.Rd with \alias{foo}

The check says

Rd files with duplicated alias 'foo':
   ‘foo-package.Rd’ ‘foo.Rd’

I prevented that by manually setting the aliases in foo-package.R to 
foo-package only, as

#'@keywords internal

#'@aliases foo-package

  "_PACKAGE"

Best,

Thomas

On 8/20/23 12:00, r-package-devel-request using r-project.org wrote:
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Sat, 19 Aug 2023 12:54:40 +0000
> From: Daniel Kelley <kelley using dal.ca>
> To: R package devel <r-package-devel using r-project.org>
> Subject: [R-pkg-devel] possible solution to
> 	package-documentation-alias problem
> Message-ID: <E79A0C00-6FE3-48DA-AAC3-29A63D28A452 using dal.ca>
> Content-Type: text/plain; charset="us-ascii"
>
> # Preamble
>
> This email is to tell other developers what I did to address an issue with
> documenting a package.  I'm not sure that I am correct in my approach --
> comments would definitely be appreciated -- but at least this email is fairly
> concrete about the changes I made. To be honest, I don't know how to test
> whether my changes are suitable, since no problem is reported in local builds or
> in remote windows checks, and no problem is listed on the CRAN tests page.
>
> # The problem
>
> Today I received multiple emails from K. Hornik, telling me about problems with
> the package-level documentation for several CRAN packages that I maintain. Here
> is a key part of that email:
>
>      You have file 'oce/man/oce.Rd' with \docType{package}, likely intended as a
>      package overview help file, but without the appropriate PKGNAME-package
>      \alias as per "Documenting packages" in R-exts.
>
> # Possible solution
>
> As a test (using the 'plan' package, which is much smaller and thus ought to
> give faster test results), I changed my Roxygen2 block
>
>      #' @name plan
>      #' @docType package
>      #' @author Dan Kelley
>      NULL
>
> to read
>
>      #' @name plan
>      #' @docType package
>      #' @author Dan Kelley
>      #' @keywords internal
>      "_PACKAGE"
>      ## usethis namespace: start
>      ## usethis namespace: end
>      NULL
>
> Note that the two ## comments are likely not required, but I included them
> because I saw them at
>
> https://github.com/jonesor/mpmsim/commit/e8d0f0d657ffa24c25ddd3165c7ddcad16322e3d
>
> which I found to be quite a helpful resource.
>
> # Local testing
>
> After rebuilding locally, I can now do
>
>      package?plan
>
> and get the expected documentation for the package as a whole.
>
> # CRAN submission
>
> I submitted the update to CRAN, and it has appeared as a tarball.  It has not
> yet appeared in built-up packages sources, but perhaps the fact that I didn't
> get any warnings from CRAN suggests that the flaw has been addressed.
>
> # Conclusions
>
> If I am right, a simple fix is all that will be required for many packages.
> However, I don't know of any way to know if this fix follows recommended
> procedures.  There appear to be multiple ways of addressing the issue.
>
> Perhaps other developers will have better solutions than the one I've outlined
> above.  Or, if I happen to have done something right, then perhaps this email
> will be of some use to other developers.
>
> Dan Kelley / Department of Oceanography / Dalhousie University / Canada
>