@inheritParams for S4 methods

How do I inherit these params from odbc::dbConnect() We have an internal function for connecting to our database and we want to list out the parameters that are available.

In the help menu I see this
               image

However, when I use:

  • @inheritParams odbc::dbConnect in only brings back drv and ... definition
  • @inheritDotParams odbc::dbConnect it only brings back drv

When trying to understand what R is seeing, this lists the parameters of the help menu

  • formals(odbc:::OdbcConnection)

but roxygen2 won't use it (error: failed to find topic), and this only shows the parameters I described above

  • formals(odbc:::dbConnect)

Any help would be appreciated

1 Like

Hi @rjake

You'd have to tell R to inherit the parameters from the method and not the generic:

@inheritParams odbc::`dbConnect,OdbcDriver-method`

Best regards,
Marcel
@LiNk-NY

Thanks for the suggestion. I tried it, but it still just returns the ... definition:

Also, how did you find that answer? I haven't been able to google anything that points me in that direction.

Actually, it seems that you can also use inheritParams with the odbc or the dbConnect generics (they are aliases in the documentation), e.g. :

  • @inheritParams odbc::odbc
  • @inheritParams odbc::dbConnect

If it only returns the ... definition then perhaps your method definition does not include those parameters.

Here is a roxygen block that correctly inherits the parameters:

#' @name odbc-foo
#' @aliases dbConnect,Foo-method
#'
#' @title Connect to a database
#'
#' @description Testing inheritParams
#'
#' @importFrom odbc dbConnect
#' @inheritParams odbc::dbConnect
#' @exportMethod dbConnect
setMethod("dbConnect", "Foo", function(drv, ..., timezone, timezone_out, encoding, bigint) {
   I()
})

PS. I would rather inherit from the method, i.e., @inheritParams odbc::'dbConnect,OdbcDriver-method', it is safer in case the aliases change.
How did I find the answer? I work with S4 methods all the time :slight_smile:

3 Likes

I see. I think the issue is we aren't making our own method. We just have a function that allows the user to pass their own connection object or default to a prod connection. This is just a skeleton, there are more steps inside of run_sql()

run_sql <- function(sql, con = NULL, ...) {
  if (missing(con)) {
   con <- db_prod() # custom function
  }

  dbGetQuery(con, sql, ...) # the '...' we want to document

  if (missing(con)) {
   dbDisconnect(con)
 }
}

It should also work with a plain function as long as the function signature shares arguments in the referenced documentation. In this case, it only seems to share the dots ....

The ... you want to document don't seem to go to the place you think they are going to. If you expect con to be an OdbcConnection then the dots go to this method:

> getMethod(dbGetQuery, c("OdbcConnection","character"))
Method Definition:

function (conn, statement, ...) 
{
    .local <- function (conn, statement, n = -1, params = NULL, 
        immediate = is.null(params), ...) 
    {
        rs <- dbSendQuery(conn, statement, params = params, immediate = immediate, 
            ...)
        on.exit(dbClearResult(rs))
        df <- dbFetch(rs, n = n, ...)
        if (!dbHasCompleted(rs)) {
            warning("Pending rows", call. = FALSE)
        }
        df
    }
    .local(conn, statement, ...)
}

which actually go to the dbSendQuery,OdbcConnection,character-method and to dbFetch.

AFAIU, you expect con to be created with dbConnect with an odbc() driver. This would happen outside of your function and therefore you don't need to inheritParams for a function that is external to yours.