Best practices for documenting re-exports?

[mmuurr]

I've been trying to figure out how dplyr's pkgdown-generated reference site builds this page on re-exports. I can't find anything in the dplyr repo that specifies that page (in particular, I don't see any reference to such a page in _pkgdown.yml). I also can't find any explicit mention of special 're-export' handling in roxygen2's docs.

On the specific re-exported functions in dplyr, I see various @name and @rdname pairings ... setops (in sets.r) being a perfectly good example. But I can't find any structure that says setops should be documented on that re-exports page by pkgdown :-/

Does anyone know how that re-exports page is (seemingly automatically) built?

BTW, I (naïvely?) tried something like the below, and roxygen2/pkgdown don't build a re-export page even when named explicitly, so clearly I'm doing something wrong!

#' Re-exports
#'
#' This description causes roxygen2 to throw a warning.
#'
#' @name re-exports
NULL

#' @rdname re-exports
#' @importFrom magrittr `%>%` `%T>%`
#' @export
magrittr::`%>%`
#' #export
magrittr::`%T>%`
 
#' @rdname re-exports
#' @importFrom mypkg foo bar
#' @export
mypkg::foo
#' #export
mypkg::bar

(And while we're on the topic, is there an easier/more-concise pattern for re-exports ... or is this still the standard best practice?)

[mmuurr]

I've mostly figured this out, though it required reading through roxygen2's tests to understand the implicit behavior (as I couldn't find any formal documentation on this topic).

The short recipe is:

1. Re-export using this roxygen2 tag pattern:

   #' @importFrom pkg symbol
   #' @export
   pkg::symbols
   

   (The explicit :: notation is required.)
2. Do *not add other tags. In particular, avoid the @description tag (or it's implied text as the second #' paragraph)
3. Upon building your docs (e.g. via devtools::document()) this will create an .Rd help topic called "reexports". (You can see that topic now with ?yourpkg::reexports.)
4. By default, pkgdown::build_site() will not include the "reexports" topic, so you'll need to explicitly add it to your _pkgdown.yml config file, like so:

   reference:
   - title: some section
   - contents:
     - topic1
     - topic2
     - reexports
   

Hopefully this is helpful to others that want to re-export some objects/functions.