include ... in @inheritDotParams lists?

[d-morrison]

#633 has continued to accumulate additional reports after being closed, so I'm opening a new issue here.

As others have said, @inheritDotParams currently (r-lib/pkgdown@de95b13) omits ... from the list of inherited arguments when the function being inherited from has its own ... argument.

Here's a reprex, modifying the one in #633 (comment):

#' @title API function
#' @inheritDotParams middle
api <- function(...) {
  middle(...)
}

#' @title intermediate function
#' @param arg1 a parameter argument
#' @inheritDotParams core
middle <- function(arg1, ...) {
  core(...)
}

#' @title core function
#' @param arg2 another parameter argument
core <- function(arg2) {
  # do stuff
}

pkgdown writes api.Rd as

\name{api}
\alias{api}
\title{API function}
\usage{
api(...)
}
\arguments{
\item{...}{
  Arguments passed on to \code{\link[=middle]{middle}}
  \describe{
    \item{\code{arg1}}{a parameter argument}
  }}
}
\description{
API function
}

which renders as:

Instead, I'd like api.Rd to be:

\name{api}
\alias{api}
\title{API function}
\usage{
api(...)
}
\arguments{
\item{...}{
  Arguments passed on to \code{\link[=middle]{middle}}
  \describe{
    \item{\code{arg1}}{a parameter argument}
    \item{\code{...}}{Arguments passed on from \code{\link[=middle]{middle}} to \code{\link[=core]{core}}}
  }}
}
\description{
API function
}

with corresponding render:

Then, users of api() would be able to immediately tell that ... arguments passed to api() flow down to core() if they are not intercepted by middle().

Alternatively, inherited parameters from the whole function hierarchy could be listed directly in api.Rd, but that might get too messy, as discussed in #633 (comment).

I realize that there's a workaround using two @inheritDotParams tags:

#' @title API function
#' @inheritDotParams middle
#' @inheritDotParams core
api <- function(...) {
  middle(...)
}

However, this workaround is a bit brittle; if I later change middle() to now call core2() instead of core(), then using this workaround, I have to go back and update the @inheritDotParams tags in both middle() and api().