From b494e23240ffb2ee955f0065b99fcdbf7e1a38b7 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Tue, 21 Nov 2023 14:45:36 -0600
Subject: [PATCH] Re-exports improvements (#1545)

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

Fixes #1408
---
 NEWS.md                               |  5 +++
 R/object-defaults.R                   |  9 ++++++
 tests/testthat/test-object-defaults.R | 44 +++++++++++++++++++++++++++
 tests/testthat/test-object-import.R   | 11 +++++--
 4 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 4d806e3e..ee6a4a52 100644
--- a/NEWS.md
+++ b/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,
diff --git a/R/object-defaults.R b/R/object-defaults.R
index d9292844..140cfa0c 100644
--- a/R/object-defaults.R
+++ b/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"),
diff --git a/tests/testthat/test-object-defaults.R b/tests/testthat/test-object-defaults.R
index 260e12f6..d64d4211 100644
--- a/tests/testthat/test-object-defaults.R
+++ b/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", {
diff --git a/tests/testthat/test-object-import.R b/tests/testthat/test-object-import.R
index c1c253b5..c954cc0a 100644
--- a/tests/testthat/test-object-import.R
+++ b/tests/testthat/test-object-import.R
@@ -1,7 +1,9 @@
 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"),
@@ -9,8 +11,11 @@ test_that("exporting a call to :: produces re-exports documentation", {
   )
   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", {