Add argument selection to @inheritParams (#1852)

Fixes #1849

Author: hadley

NEWS.md

@@ -6,7 +6,8 @@
   * S7 methods registered with `method(generic, class) <- fn` are detected automatically and generate usage with `## S7 method for class <ClassName>`.
 * roxygen2 no longer depends on stringr/stringi. This means that no package in the devtools constellation depends on stringr, which in turn means you no longer need stringi, making it a bit easier to install in constrained Linux environments.
 * roxygen2 options can now be set using `Config/roxygen2/` fields in DESCRIPTION (e.g. `Config/roxygen2/markdown: TRUE`) instead of the `Roxygen` field. The old `Roxygen` field is still supported. Similarly, the roxygen2 version is now stored in `Config/roxygen2/version` instead of `RoxygenNote` (#1328).
-* Tags that expect single-line input now warn when they span multiple lines, catching common mistakes. Affected tags: `@aliases`, `@concept`, `@encoding`, `@exportClass`, `@exportMethod`, `@exportPattern`, `@exportS3Method`, `@importFrom`, `@importClassesFrom`, `@importMethodsFrom`, `@include`, `@inheritParams`, `@keywords`, `@method`, `@name`, `@order`, `@rdname`, `@S3method`, `@template`, and `@useDynLib` (#1642, #1688). This may break some existing usage, but it prevents a wide class of otherwise silent errors.
+* Tags that expect single-line input now warn when they span multiple lines, catching common mistakes. Affected tags: `@aliases`, `@concept`, `@encoding`, `@exportClass`, `@exportMethod`, `@exportPattern`, `@exportS3Method`, `@importFrom`, `@importClassesFrom`, `@importMethodsFrom`, `@include`, `@keywords`, `@method`, `@name`, `@order`, `@rdname`, `@S3method`, `@template`, and `@useDynLib` (#1642, #1688). This may break some existing usage, but it prevents a wide class of otherwise silent errors.
+* `@inheritParams` now supports argument filtering using the same syntax as `@inheritDotParams`. For example, `@inheritParams foo x y` inherits only `x` and `y`, and `@inheritParams foo -z` inherits everything except `z` (#1849).
 * `@examplesIf` now warns when there is no example code after the condition (#1695).
 * `tag_words_line()` is deprecated in favour of `tag_words()`, which now checks for single-line content by default. Use `tag_words(x, multiline = TRUE)` or `tag_value(x, multiline = TRUE)` if your tag legitimately spans multiple lines.
 * R6 improvements:

R/rd-inherit.R

@@ -8,10 +8,21 @@ roxy_tag_rd.roxy_tag_inherit <- function(x, base_path, env) {
 }
 
 #' @export
-roxy_tag_parse.roxy_tag_inheritParams <- function(x) tag_value(x)
+roxy_tag_parse.roxy_tag_inheritParams <- function(x) {
+  tag_two_part(
+    x,
+    "a source",
+    "an argument list",
+    required = FALSE,
+    markdown = FALSE
+  )
+}
 #' @export
 roxy_tag_rd.roxy_tag_inheritParams <- function(x, base_path, env) {
-  rd_section_inherit(x$val, list("params"))
+  list(
+    rd_section_inherit(x$val$name, list("params")),
+    rd_section_inherit_params_args(x$val$name, x$val$description)
+  )
 }
 
 #' @export
@@ -107,6 +118,28 @@ merge.rd_section_inherit_dot_params <- function(x, y, ...) {
   )
 }
 
+rd_section_inherit_params_args <- function(source, args) {
+  check_string(source)
+  check_string(args)
+
+  if (!nzchar(args)) {
+    return(NULL)
+  }
+  rd_section("inherit_params_args", list(source = source, args = args))
+}
+
+#' @export
+format.rd_section_inherit_params_args <- function(x, ...) NULL
+
+#' @export
+merge.rd_section_inherit_params_args <- function(x, y, ...) {
+  stopifnot(identical(class(x), class(y)))
+  rd_section_inherit_params_args(
+    c(x$value$source, y$value$source),
+    c(x$value$args, y$value$args)
+  )
+}
+
 
 # Process inheritance -----------------------------------------------------
 
@@ -168,13 +201,26 @@ inherit_params <- function(topic, topics) {
   # Work through inherited params seeing if any match the parameters
   # we're missing
   for (inheritor in inheritors) {
+    source <- topic$get_name()
     inherited_params <- find_params(
       inheritor,
       topics,
-      source = topic$get_name(),
+      source = source,
       tag = "@inheritParams"
     )
 
+    # Apply argument filter if specified via @inheritParams foo args
+    params_args <- topic$get_value("inherit_params_args")
+    args_filter <- params_args$args[params_args$source == inheritor]
+    if (length(args_filter) == 1 && args_filter != "") {
+      doc_args <- map_chr(inherited_params, "[[", "name")
+      selected <- select_args_text(doc_args, args_filter, topic_name = source)
+      inherited_params <- Filter(
+        function(p) any(p$name %in% selected),
+        inherited_params
+      )
+    }
+
     for (param in inherited_params) {
       match <- match_param(param$name, missing)
       if (!is.null(match)) {

R/select-args.R

@@ -11,7 +11,7 @@ select_args_text <- function(args, select, topic_name) {
       select_args(args, parsed)
     },
     error = function(e) {
-      warn_roxy_topic(topic_name, "@inheritDotsParam failed", parent = e)
+      warn_roxy_topic(topic_name, "argument selection failed", parent = e)
       character()
     }
   )

inst/roxygen2-tags.yml

@@ -228,7 +228,9 @@
   description: >
     Inherit argument documentation from another function. Only inherits
     documentation for arguments that aren't already documented locally.
-  template: ' ${1:source}'
+    Optionally followed by a list of argument names to include or exclude,
+    using the same syntax as `@inheritDotParams`.
+  template: ' ${1:source} ${2:arg1 arg2 arg3}'
   vignette: reuse
   recommend: true
 

tests/testthat/_snaps/rd-inherit.md

@@ -70,7 +70,7 @@
     Code
       . <- roc_proc_text(rd_roclet(), text)
     Message
-      x In topic 'bar': @inheritDotsParam failed.
+      x In topic 'bar': argument selection failed.
       Caused by error in `FUN()`:
       ! object 'z' not found
       x In topic 'bar': @inheritDotParams failed.

tests/testthat/_snaps/select-args.md

@@ -3,7 +3,7 @@
     Code
       select_args_text(c("x", "na.rm"), "-xlab:", "test")
     Message
-      x In topic 'test': @inheritDotsParam failed.
+      x In topic 'test': argument selection failed.
       Caused by error in `parse()`:
       ! <text>:2:0: unexpected end of input
       1: -xlab:
@@ -13,7 +13,7 @@
     Code
       select_args_text(c("x", "na.rm"), "\"a\"", "test")
     Message
-      x In topic 'test': @inheritDotsParam failed.
+      x In topic 'test': argument selection failed.
       Caused by error in `select_check()`:
       ! Argument specification must evaluate to a numeric vector.
       Problem in `"a"`.
@@ -22,7 +22,7 @@
     Code
       select_args_text(c("x", "y", "z"), "-x:z", "test")
     Message
-      x In topic 'test': @inheritDotsParam failed.
+      x In topic 'test': argument selection failed.
       Caused by error:
       ! Argument specification must be all positive or all negative, not a mixture.
       i Problem in `-x:z`.

tests/testthat/test-rd-inherit.R

@@ -676,6 +676,88 @@ test_that("inherit params ... named \\dots", {
   )
 })
 
+# inheritParams argument filtering ----------------------------------------
+
+test_that("@inheritParams can include specific args", {
+  out <- roc_proc_text(
+    rd_roclet(),
+    "
+    #' A.
+    #'
+    #' @param x X
+    #' @param y Y
+    #' @param z Z
+    a <- function(x, y, z) {}
+
+    #' B
+    #'
+    #' @inheritParams a x z
+    b <- function(x, y, z) {}
+    "
+  )[[2]]
+
+  params <- out$get_value("param")
+  expect_equal(params, c(x = "X", z = "Z"))
+})
+
+test_that("@inheritParams can exclude specific args", {
+  out <- roc_proc_text(
+    rd_roclet(),
+    "
+    #' A.
+    #'
+    #' @param x X
+    #' @param y Y
+    #' @param z Z
+    a <- function(x, y, z) {}
+
+    #' B
+    #'
+    #' @inheritParams a -y
+    b <- function(x, y, z) {}
+    "
+  )[[2]]
+
+  params <- out$get_value("param")
+  expect_equal(params, c(x = "X", z = "Z"))
+})
+
+test_that("@inheritParams filtering works with external packages", {
+  out <- roc_proc_text(
+    rd_roclet(),
+    "
+    #' My mean
+    #'
+    #' @inheritParams base::mean -na.rm
+    mymean <- function(x, trim, na.rm) {}"
+  )[[1]]
+
+  params <- out$get_value("param")
+  expect_true("trim" %in% names(params))
+  expect_false("na.rm" %in% names(params))
+})
+
+test_that("@inheritParams without args still works", {
+  out <- roc_proc_text(
+    rd_roclet(),
+    "
+    #' A.
+    #'
+    #' @param x X
+    #' @param y Y
+    a <- function(x, y) {}
+
+    #' B
+    #'
+    #' @inheritParams a
+    b <- function(x, y) {}
+    "
+  )[[2]]
+
+  params <- out$get_value("param")
+  expect_equal(params, c(x = "X", y = "Y"))
+})
+
 # inheritDotParams --------------------------------------------------------
 
 test_that("can inherit all from single function", {

vignettes/reuse.Rmd

@@ -181,9 +181,13 @@ Since no other function in dplyr has an argument with this name, its documentati
 
 ### Recursive inheritance
 
-`@inheritParams` (like all `@inherits` functions) works recursively, so if `g` inherits parameters from `h`, then `f` can also inherit those parameters from `g`.
-However, this technique is best used sparingly: it's very easy to create complex dependency webs that are hard to reason about where making changing the documentation in one function cascades out in unexpected ways across your package.
-If you want to be more explicit, you should consider writing helper functions and using inline R code, as described below.
+`@inheritParams` (like all `@inherits` functions) works recursively, so if `g` inherits parameters from `h`, then `f` can also inherit those parameters from `g`. 
+However, this technique is best used sparingly: it's very easy to create complex dependency webs that are hard to reason about where making changing the documentation in one function cascades out in unexpected ways across your package. 
+You can avoid this problem by being more explicit about which parameters are inherited:
+
+-   `@inheritParams foo x y` inherits only `x` and `y`.
+-   `@inheritParams foo -z` inherits all parameters except `z`.
+-   `@inheritParams foo first:third` inherits parameters `first` through `third` (in argument order).
 
 ### Multiple parameters