Warn if @inheritParams used when not needed

Fixes #836

Author: hadley

NEWS.md

@@ -1,5 +1,8 @@
 # roxygen2 (development version)
 
+* `@inheritParams` warns if there are no parameters that require 
+  documentation (#836).
+
 * roxygen2 now recgonises fully qualified S4 functions like 
   `methods::setGeneric()`, `methods::setClass()` and `methods::setMethod()`
   (#880).

R/rd-inherit.R

@@ -26,19 +26,28 @@ topics_process_inherit <- function(topics, env) {
 # Inherit parameters -----------------------------------------------------------
 
 inherit_params <- function(topic, topics) {
+  inheritors <- topic$inherits_from("params")
+  if (length(inheritors) == 0) {
+    return()
+  }
+
   documented <- get_documented_params(topic)
   needed <- topic$get_field("formals")$values
-
   missing <- setdiff(needed, documented)
   if (length(missing) == 0) {
+    warn(paste0(
+      "Topic '", topic$get_name(), "': ",
+      "no parameters to inherit with @inheritParams"
+    ))
     return()
   }
 
-  for (inheritor in topic$inherits_from("params")) {
+  for (inheritor in inheritors) {
     inherited <- find_params(inheritor, topics)
 
     to_add <- intersect(missing, names(inherited))
     if (length(to_add) == 0) {
+      # Can't warn here because @inherit inherits parameters
       next
     }
 

R/topic.R

@@ -32,6 +32,10 @@ RoxyTopic <- R6::R6Class("RoxyTopic", public = list(
     self$fields[[field_name]]
   },
 
+  get_name = function() {
+    self$get_field("name")$values
+  },
+
   inherits_from = function(type) {
     if (!self$has_field("inherit")) {
       return(character())

tests/testthat/test-rd-inherit.R

@@ -310,13 +310,23 @@ test_that("@inheritParam understands compound docs", {
     #' Title
     #'
     #' @inheritParams x
-    #' @param x y
     #' @param y y
     y <- function(x, y) {}")[[2]]
   params <- get_tag(out, "param")$values
-  expect_equal(params, c(x = "y", y = "y"))
+  expect_equal(params, c(x = "x", y = "y"))
 })
 
+test_that("warned if no params need documentation", {
+  code <- "
+    #' Title
+    #'
+    #' @param x x
+    #' @param y x
+    #' @inheritParams foo
+    x <- function(x, y) {}
+  "
+  expect_warning(roc_proc_text(rd_roclet(), code), "no parameters to inherit")
+})
 
 test_that("argument order, also for incomplete documentation", {
   out <- roc_proc_text(rd_roclet(), "