More informative message when @inheritDotParams doesn't find topic (#1779)

Fixes #1602

Author: hadley

NEWS.md

@@ -5,6 +5,7 @@
 * Markdown links now do a better job of resolving package names: the process is cached for better performance (#1724); it works with infix operators (e.g. `[%in%]`) (#1728); no longer changes the link text (#1662); and includes base packages when reporting ambiguous functions (#1725).
 * Package documentation now uses `logo.svg` if available, falling back to `logo.png` (#1640).
 * `@family` no longer adds a trailing space after the colon in the default family prefix (#1628). Custom `rd_family_title` values now automatically get a colon appended if they don't already end with one (#1656).
+* `@inheritDotParams` now generates an informative warning when the source function can't be found, instead of a cryptic error (#1602).
 * `@inheritDotParams` now warns and produces no output when there are no parameters to inherit, instead of generating an empty `\describe` block that caused CRAN HTML validation warnings (#1671).
 * `@description` no longer errors when the markdown text starts with a heading (#1705).
 * Package documentation now only wraps actual URLs in the `URL` field of `DESCRIPTION` (#1420).

R/rd-inherit.R

@@ -168,7 +168,8 @@ inherit_params <- function(topic, topics) {
     inherited_params <- find_params(
       inheritor,
       topics,
-      source = topic$get_name()
+      source = topic$get_name(),
+      tag = "@inheritParams"
     )
 
     for (param in inherited_params) {
@@ -217,7 +218,13 @@ inherit_dot_params <- function(topic, topics, env) {
   args <- map2(funs, inheritors$args, select_args_text, topic = topic)
 
   # Then pull out the ones we need
-  docs <- lapply(inheritors$source, find_params, topics = topics)
+  docs <- lapply(
+    inheritors$source,
+    find_params,
+    topics = topics,
+    source = topic$get_name(),
+    tag = "@inheritDotParams"
+  )
   arg_matches <- function(args, docs) {
     match <- map_lgl(docs, \(x) all(x$name %in% args))
     matched <- docs[match]
@@ -290,8 +297,8 @@ get_documented_params <- function(topic, only_first = FALSE) {
   documented
 }
 
-find_params <- function(name, topics, source) {
-  topic <- get_rd(name, topics, source = source)
+find_params <- function(name, topics, source, tag = "@inherits") {
+  topic <- get_rd(name, topics, source = source, tag = tag)
   if (is.null(topic)) {
     return()
   }
@@ -492,36 +499,39 @@ tweak_links <- function(x, package) {
 
 # Find info in Rd or topic ------------------------------------------------
 
-get_rd <- function(name, topics, source) {
+get_rd <- function(name, topics, source, tag = "@inherits") {
   if (is_namespaced(name)) {
     # External package
     parsed <- parse_expr(name)
     pkg <- as.character(parsed[[2]])
     fun <- as.character(parsed[[3]])
 
-    get_rd_from_help(pkg, fun, source)
+    get_rd_from_help(pkg, fun, source, tag = tag)
   } else {
     # Current package
     rd_name <- topics$find_filename(name)
     if (identical(rd_name, NA_character_)) {
-      warn_roxy_topic(source, "@inherits failed to find topic {.str {name}}")
+      warn_roxy_topic(
+        source,
+        "{tag} failed to find topic {.str {name}} in current package"
+      )
     }
     topics$get(rd_name)
   }
 }
 
-get_rd_from_help <- function(package, alias, source) {
+get_rd_from_help <- function(package, alias, source, tag = "@inherits") {
   if (!is_installed(package)) {
     warn_roxy_topic(
       source,
-      "@inherits failed because {.pkg {package}} is not installed"
+      "{tag} failed because {.pkg {package}} is not installed"
     )
     return()
   }
 
   help <- utils::help((alias), (package))
   if (length(help) == 0) {
-    warn_roxy_topic(source, "@inherits failed to find topic {package}::{alias}")
+    warn_roxy_topic(source, "{tag} failed to find topic {package}::{alias}")
     return()
   }
 

tests/testthat/_snaps/rd-inherit.md

@@ -84,30 +84,33 @@
       x In topic 'bar': @inheritDotParams failed.
       i No arguments inherited from `foo()`.
 
-# useful warnings if can't find topics
+# inheritDotParams warns when source not found (#1602)
 
     Code
-      get_rd("base2::attach", source = "source")
+      . <- roc_proc_text(rd_roclet(), text)
     Message
-      x In topic 'source': @inherits failed because base2 is not installed.
-    Output
-      NULL
+      x In topic 'test': @inheritDotParams failed to find topic "format" in current package.
+      x In topic 'test': @inheritDotParams failed.
+      i No arguments inherited from `format()`.
+
+# useful warnings if can't find topics
+
     Code
-      get_rd("base::function_not_found", source = "source")
+      get_rd("not_installed::pkg", source = "source")
     Message
-      x In topic 'source': @inherits failed to find topic base::function_not_found.
+      x In topic 'source': @inherits failed because not_installed is not installed.
     Output
       NULL
     Code
-      get_rd("function", RoxyTopics$new(), source = "source")
+      get_rd("base::doesntexist", source = "source")
     Message
-      x In topic 'source': @inherits failed to find topic "function".
+      x In topic 'source': @inherits failed to find topic base::doesntexist.
     Output
       NULL
     Code
-      get_rd("foo::bar()", RoxyTopics$new(), source = "source")
+      get_rd("doesntexist", RoxyTopics$new(), source = "source")
     Message
-      x In topic 'source': @inherits failed to find topic "foo::bar()".
+      x In topic 'source': @inherits failed to find topic "doesntexist" in current package.
     Output
       NULL
 

tests/testthat/test-rd-inherit.R

@@ -817,6 +817,14 @@ test_that("warns when no params to inherit (#1671)", {
   expect_false("..." %in% names(out[["bar.Rd"]]$get_value("param")))
 })
 
+test_that("inheritDotParams warns when source not found (#1602)", {
+  text <- "
+    #' Test
+    #' @inheritDotParams format
+    test = function(...) {}
+  "
+  expect_snapshot(. <- roc_proc_text(rd_roclet(), text))
+})
 
 # inherit everything ------------------------------------------------------
 
@@ -861,10 +869,9 @@ test_that("can inherit all from single function", {
 
 test_that("useful warnings if can't find topics", {
   expect_snapshot({
-    get_rd("base2::attach", source = "source")
-    get_rd("base::function_not_found", source = "source")
-    get_rd("function", RoxyTopics$new(), source = "source")
-    get_rd("foo::bar()", RoxyTopics$new(), source = "source")
+    get_rd("not_installed::pkg", source = "source")
+    get_rd("base::doesntexist", source = "source")
+    get_rd("doesntexist", RoxyTopics$new(), source = "source")
   })
 })