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

[Duncan Murdoch]

That seems like a bug that should be reported to the Roxygen authors.

Duncan Murdoch

On 20/08/2023 8:22 a.m., Thomas Rusch wrote:
> 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
>>
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel