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

Sun, Aug 20, 2023 5:22 AM

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 at r-project.org wrote:

----------------------------------------------------------------------

Message: 1
Date: Sat, 19 Aug 2023 12:54:40 +0000
From: Daniel Kelley <kelley at dal.ca>
To: R package devel <r-package-devel at r-project.org>
Subject: [R-pkg-devel] possible solution to
	package-documentation-alias problem
Message-ID: <E79A0C00-6FE3-48DA-AAC3-29A63D28A452 at 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-pkg-devel] possible solution to package-documentation-alias problem

Thread (3 messages)