R devel - Jun 2020 - roxygen2 / documentation of reexports

Dear colleagues,

preparing a release of my package ?polmineR? I encountered the following issue
with a new warning issued when running R CMD check with the --as-cran option on
Debian with R-devel.

To reexport the magrittr pipe operator %>%, my package adopted I snippet
you?d see in the dplyr package, for instance:

#' @importFrom magrittr %>%
#' @export
magrittr::`%>%`

The dplyr package has many statements of this kind and I guess the pattern is
common. Roxygn2 will prepare a file documenting the reexport. But the Rd file
prepared by Roxygen2 will result in an error saying ?Non-file package-anchored
link(s) in documentation object?.

The part of the Rd file that is not in line with CRAN requirements is:
\code{\link[magrittr]{\%>\%}}

Looking around for a solution, I realized that the DT package was adopted
recently to address the issue (commit message ?fix the R-devel issue about
documentation links?):
https://github.com/rstudio/DT/commit/99daef8fcd376c285f3a82be753b80dee7ae3670

The snippet to do the reexport is somewhat different (I report magrittr pipe
only):

#' @importFrom magrittr %>%
#' @export %>%
NULL

But on this basis, roxygen2 will not prepare the Rd file for the reexports
automatically. As I understand it, an Rd file for the DT package that works and
meets the requirements of R-devel has been written manually
(https://github.com/rstudio/DT/blob/master/man/DT-imports.Rd). So this is what I
did for my polmineR package because I need to get it published asap (it has been
archived). It works and it passes tests. So far so good.

I like to use roxygen2 systematically and I dislike having to write the
reexports single file manually. So does anybody know another solution?

Checking / testing dplyr (master branch) on my Debian R-devel test environment,
I realize that dplyr has many reexports that are documented in a manner that
evokes the same issues I have seen. I assume that further packages will
encounter this issue.

Kind regards
Andreas (Bl?tte)

--
Prof. Dr. Andreas Bl?tte
Professor of Public Policy and Regional Politics
University of Duisburg-Essen



	[[alternative HTML version deleted]]

You can fix this with the dev version of roxygen, you can get it from
https://github.com/r-lib/roxygen2

roxygen 7.1.1 with the fix will be on CRAN shortly, hopefully:
https://github.com/r-lib/roxygen2/issues/1126

See more about this issue here:
https://www.mail-archive.com/r-package-devel at r-project.org/msg05502.html
https://github.com/r-lib/roxygen2/pull/1109

Gabor

On Sat, Jun 27, 2020 at 1:18 PM Bl?tte, Andreas
<andreas.blaette at uni-due.de> wrote:
>
> Dear colleagues,
>
> preparing a release of my package ?polmineR? I encountered the following
issue with a new warning issued when running R CMD check with the --as-cran
option on Debian with R-devel.
>
> To reexport the magrittr pipe operator %>%, my package adopted I snippet
you?d see in the dplyr package, for instance:
>
> #' @importFrom magrittr %>%
> #' @export
> magrittr::`%>%`
>
> The dplyr package has many statements of this kind and I guess the pattern
is common. Roxygn2 will prepare a file documenting the reexport. But the Rd file
prepared by Roxygen2 will result in an error saying ?Non-file package-anchored
link(s) in documentation object?.
>
> The part of the Rd file that is not in line with CRAN requirements is:
\code{\link[magrittr]{\%>\%}}
>
> Looking around for a solution, I realized that the DT package was adopted
recently to address the issue (commit message ?fix the R-devel issue about
documentation links?):
>
https://github.com/rstudio/DT/commit/99daef8fcd376c285f3a82be753b80dee7ae3670
>
> The snippet to do the reexport is somewhat different (I report magrittr
pipe only):
>
> #' @importFrom magrittr %>%
> #' @export %>%
> NULL
>
> But on this basis, roxygen2 will not prepare the Rd file for the reexports
automatically. As I understand it, an Rd file for the DT package that works and
meets the requirements of R-devel has been written manually
(https://github.com/rstudio/DT/blob/master/man/DT-imports.Rd). So this is what I
did for my polmineR package because I need to get it published asap (it has been
archived). It works and it passes tests. So far so good.
>
> I like to use roxygen2 systematically and I dislike having to write the
reexports single file manually. So does anybody know another solution?
>
> Checking / testing dplyr (master branch) on my Debian R-devel test
environment, I realize that dplyr has many reexports that are documented in a
manner that evokes the same issues I have seen. I assume that further packages
will encounter this issue.
>
> Kind regards
> Andreas (Bl?tte)
>
> --
> Prof. Dr. Andreas Bl?tte
> Professor of Public Policy and Regional Politics
> University of Duisburg-Essen
>
>
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel