Documentation for S7 methods with additional arguments to the generic

[mitchelloharawild]

Documenting S7 methods with additional non-generic arguments triggers CRAN check warnings since the methods themselves are invisible to the checks. I don't see an elegant fix for this without R changes that make the CRAN checks aware of S7 method arguments. An inelegant solution could be to separately document the S7 method usage and arguments in an Rd section (e.g. Methods) which is outside the attention of CRAN checks.

MRE:

#' Size of an object
#'
#' @description
#' `size()` determines the size of an object.
#'
#' # Methods
#' `size()` is an S7 generic with methods available for the following
#' classes:
#'
#' `r doclisting::methods_list("size")`
#'
#' @param x An object.
#' @param ... Not used.
#' @returns A single number.
#' 
#' @export
size <- S7::new_generic("size", "x")

#' @rdname size
#' @param na.rm If TRUE, missing values are not included in the calculation of the size of an object.
S7::method(size, S7::class_any) <- function(x, ..., na.rm = FALSE) {
  if (na.rm) x <- x[!is.na(x)]
  length(x)
}

Produces the CRAN check warning:

❯ checking for code/documentation mismatches ... WARNING
  Codoc mismatches from Rd file 'size.Rd':
  size
    Code: function(x, ...)
    Docs: function(x, ..., na.rm = FALSE)
    Argument names in docs not in code:
      na.rm

[hadley]

Hmmm, that is annoying. Have you done any exploration of the code/documentation implementation to see if there's some hack we could use? (e.g. how does it work for S3 methods?)

[mitchelloharawild]

I did a bit of digging, it is from tools::codoc() which finds S3

https://github.com/wch/r-source/blob/008cb78bde378fff58261bd383b4d3d557ccc257/src/library/tools/R/QC.R#L368-L383

and S4

https://github.com/wch/r-source/blob/008cb78bde378fff58261bd383b4d3d557ccc257/src/library/tools/R/QC.R#L535-L553

methods explicitly.

I'm not familiar enough with S7's internals for how it interacts with the S3 table, but perhaps that is a direction for a hack to pass the codoc() checks.

[hadley]

I looked at them a bit but the problem is that they generate a comment before the usage which I don't want. I thought we might be able to do something like this:

\newcommand{\S7method}{#1‎}

(where there's an invisible space after #1). That makes an unparseable usage (and hence skips the codoc check) but then that fails with:

   Bad \usage lines found in Rd file 'size.Rd':
     size‎(x, ..., na.rm = FALSE)
   
   Functions with \usage entries need to have the appropriate \alias
   entries, and all their arguments documented.
   The \usage entries must correspond to syntactically valid R code.
   See chapter ‘Writing R documentation files’ in the ‘Writing R
   Extensions’ manual.

[hadley]

I think we're going to have to figure out a minimal patch for base R to resolve this 😞

@t-kalinowski