Re: [R-pkg-devel] possible solution to package-documentation-alias problem
On 20 August 2023 at 09:22, Duncan Murdoch wrote: | That seems like a bug that should be reported to the Roxygen authors. Seb did so in June: https://github.com/r-lib/roxygen2/issues/1491 There has not been a response (but given the CRAN email to many maintainers it has now been referenced mulitple times). Dirk -- dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] possible solution to package-documentation-alias problem
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-requ...@r-project.org wrote: -- Message: 1 Date: Sat, 19 Aug 2023 12:54:40 + From: Daniel Kelley To: R package devel Subject: [R-pkg-devel] possible solution to package-documentation-alias problem Message-ID: 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@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] possible solution to package-documentation-alias problem
When you get a note from CRAN, remember that it ignores Roxygen comments completely. It's just looking at the files that Roxygen produces. So you should look at the .Rd files when you get a complaint about them. Your previous code would have produced a file named plan.Rd, and that file didn't include the "plan-package" alias that was requested. The new version does, so things are now fine. I think that up until a few years ago, the old version would have worked, but this news item from 2019 hints at the change: "Using @docType package no longer automatically adds -name. Instead document _PACKAGE to get all the defaults for package documentation, or use @name to override the default file name." Duncan Murdoch On 19/08/2023 8:54 a.m., Daniel Kelley wrote: # 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@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel