Re-exports improvements (#1545)

* Automatically import the function
* Opt-out of default behaviour by setting `name` or `@rdname`.

Fixes #1408

NEWS.md

@@ -1,5 +1,10 @@
 # roxygen2 (development version)
 
+* If you document a function from another package it is automatically 
+  imported. Additionally, if you set `@rdname` or `@name` you can opt out 
+  of the default `reexports` topic generation and provide your own docs 
+  (#1408).
+
 * The NAMESPACE roclet now reports if you have S3 methods that are missing
   an `@export` tag. All S3 methods need to be `@export`ed (which confusingly
   really registers the method) even if the generic is not. This avoids rare,

R/object-defaults.R

@@ -74,7 +74,16 @@ object_defaults.package <- function(x, block) {
 
 #' @export
 object_defaults.import <- function(x, block) {
+
+  importFrom <- roxy_generated_tag(block, "importFrom", c(x$value$pkg, x$value$fun))
+
+  if (block_has_tags(block, c("rdname", "name"))) {
+    obj <- object_from_name(x$value$fun, asNamespace(x$value$pkg), block)
+    return(c(list(importFrom), object_defaults(obj, block)))
+  }
+
   list(
+    importFrom,
     roxy_generated_tag(block, "docType", "import"),
     roxy_generated_tag(block, "name", "reexports"),
     roxy_generated_tag(block, "keywords", "internal"),

tests/testthat/test-object-defaults.R

@@ -43,6 +43,50 @@ test_that("@docType class automatically added to reference class objects", {
   expect_equal(out$get_value("docType"), "class")
 })
 
+
+# imports -----------------------------------------------------------------
+
+test_that("only generates re-exports if no @name or @rdname", {
+  block <- "
+    #' @export
+    stats::median
+  "
+  out <- roc_proc_text(rd_roclet(), block)[[1]]
+  expect_equal(out$get_value("name"), "reexports")
+  expect_equal(out$get_value("keyword"), "internal")
+
+  block <- "
+    #' Title
+    #' @name stats-imports
+    #' @export
+    stats::median
+
+    #' @rdname stats-imports
+    stats::acf
+  "
+  out <- roc_proc_text(rd_roclet(), block)[[1]]
+  expect_equal(out$get_value("name")[[1]], "stats-imports")
+  expect_equal(out$get_value("alias"), c("stats-imports", "median", "acf"))
+  expect_equal(out$get_value("keyword"), NULL)
+})
+
+test_that("imports are automatically imported", {
+  block <- "
+    #' @export
+    stats::median
+  "
+  out <- roc_proc_text(namespace_roclet(), block)
+  expect_equal(out, c("export(median)", "importFrom(stats,median)"))
+
+  block <- "
+    #' @export
+    #' @name foo
+    stats::median
+  "
+  out <- roc_proc_text(namespace_roclet(), block)
+  expect_equal(out, c("export(median)", "importFrom(stats,median)"))
+})
+
 # packages -----------------------------------------------------------------
 
 test_that("can create package documentation", {

tests/testthat/test-object-import.R

@@ -1,16 +1,21 @@
 test_that("exporting a call to :: produces re-exports documentation", {
-  out <- roc_proc_text(rd_roclet(), "
+  block <- "
     #' @export
-    testthat::auto_test")[[1]]
+    testthat::auto_test
+  "
+  out <- roc_proc_text(rd_roclet(), block)[[1]]
 
   expect_equal(
     out$get_section("reexport"),
     rd_section_reexport("testthat", "auto_test", "auto_test")
   )
   expect_equal(out$get_value("title"), "Objects exported from other packages")
   expect_equal(out$get_value("keyword"), "internal")
-
   expect_snapshot_output(cat(format(out)))
+
+  # And generates correct namespace definitions
+  out <- roc_proc_text(namespace_roclet(), block)
+  expect_equal(out, c("export(auto_test)", "importFrom(testthat,auto_test)"))
 })
 
 test_that("multiple re-exports are combined", {