S4 documentation of "[" with 'missing' arguments

Question

This question is very similar to this question but when I try the answer I receive an addition 'NOTE' following R CMD check. Although it is just a NOTE I would really like to have a completely clean check.

* checking Rd line widths ... NOTE
Error: 8: no comma in argument list following \S4method
Execution halted

I can get rid of this if I pass all the other parameters (i,j,drop) and document all of them but I don't use them. It seems to me that it would be a waste to just add in extra documentation when it isn't relevant in this case.

#' An S4 class that stores a list.
#' @export
setClass("testClass", 
                 representation(a="list"))

#' Extract parts of testClass.
#' @param x testClass
#'
setMethod("[", signature(x = "testClass"),
            function (x){
                print("void function")
            }
)

The Rd file resulting in the error:

% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/test.R
\docType{methods}
\name{[,testClass-method}
\alias{[,testClass-method}
\title{Extract all elements}
\usage{
\S4method{[}{testClass}(x)
}
\arguments{
\item{x}{testClass}
}
\description{
Extract all elements
}

The following Rd results in no error if I define and document all the arguments

% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/test.R
\docType{methods}
\name{[,testClass,missing,missing,missing-method}
\alias{[,testClass,missing,missing,missing-method}
\title{Extract all elements}
\usage{
\S4method{[}{testClass,missing,missing,missing}(x, i, j, drop)
}
\arguments{
\item{x}{testClass}

\item{i}{missing}

\item{j}{missing}

\item{drop}{missing}
}
\description{
Extract all elements
}

Nonperformance

It isn't a waste to document them. You are using a generic that has a definite signature, and anyone using that generic would have reasonable expectation that it should behave as the generic (i.e. provide i, j, etc.) unless otherwise explicitly documented. The more surprising part to me was that R CMD check was only complaining about the malformed docs, as opposed to the improper method definition. – Ulyssesumayyad

@BrodieG, this I will agree on. The method could be defined but only the documentation was complaining. Perhaps an improvement to R CMD check is needed? – Nonperformance

Answer 1

You can try try something like:

setMethod("[", signature(x="testClass", i="missing", j="missing", drop="missing"), ...)

though it seems pretty weird to me that you're not even specifying i. You could also set i to "ANY".

Also, you will likely have to update your @param tags to something like:

#' @param x testClass
#' @param i missing
#' @param j missing
#' @param drop missing

You may not care about those parameters, but you are using a generic that defines them ([) so you are pretty much obligated to define them in your method and as such should also define them in the docs to highlight your particular method is different from the generic. From ?methods:

Method definitions are required to have the same formal arguments as the generic function, since the method dispatch mechanism does not rematch arguments, for reasons of both efficiency and consistency.

Ulyssesumayyad

Thank you for the answer but this still results in NOTE and error mentioned above. I am not setting i because the intent is provide the syntax to return all the elements in the S4 class object. – Nonperformance

@Nonperformance it would be helpful if you could provide roxygen versions, R versions, as well as a minimal version of the contents of the Rd file that is causing the problems. – Ulyssesumayyad

I see, I wanted to make sure I needed to define and document all the arguments no matter what. It seems a little odd to me though that the method can be defined and would work fine without the additional arguments but only the Rd would have problems (see Rd's above). – Nonperformance

@Nonperformance I suspect this has to do with the generic in this case being a primitive, though I am unable to verify this right now. – Ulyssesumayyad

Answer 2

The issue here is that you are trying to define a method for a generic that already has a definition, and you are not providing a signature for the arguments in that generic method. Here, the generic is [ -- see ?[. The oxygen-generated Rd file is somehow generating the error because it cannot match the signature for the generic with the signature it generates automatically from your [.testClass method.

The solution: Define the full signature for the method, according to the generic's signature. The code below will not generate your error in the R CMD CHECK --as-cran.

#' An S4 class that stores a list.
#' @docType class
#' @name testClass-class
#' @export
setClass("testClass", 
         slots = c(a="list"))

#' Extract parts of testClass.
#' @param x \code{testClass} object
#' @param i index for the testClass list
#' @param j not used
#' @param drop not used
#' @param ... additional arguments not used here
#' @rdname testClass-class
#' @export
setMethod("[", signature(x = "testClass"),
          function (x, i, j, ..., drop=FALSE) {
              print("void function")
          }
)

If you run this, by the way, you can see how [ is just a method/function:

x <- new("testClass")
tmp1 <- x[1]
## [1] "void function"
tmp2 <- `[`(x, 1)
## [1] "void function"
identical(tmp1, tmp2)
## [1] TRUE

Two more things to note:

1. representation() in an S4 class definition is deprecated, use slots() instead. From ?setClass:

   representation... All these arguments are deprecated from version 3.0.0 of R and should be avoided.

2. You only need to @export the class definition if you want others to be able to extend it. Exporting the method is strictly speaking, not necessary, but advised. See https://cran.r-project.org/web/packages/roxygen2/vignettes/namespace.html.

Endamoeba