Question: Trouble documenting S7 methods for `[`, `[<-`, `[[`, and `[[<-` in R package

[RodrigoZepeda]

I'm developing an R package using S7 classes and encountering issues documenting subsetting methods ([, [<-, [[, [[<-) with devtools::document() and devtools::check().

The Problem

I've tried two approaches to document S7 methods:

Approach 1: Basic documentation (fails)

#' Extract a view from the vector
#' blah blah blah
#' @export
S7::method(`[`, cool_vector) <- function(x, i, ...) {
  x@vec[i]
}

error with devtools::document()

Block must have a @name.
ℹ Either document an existing object or manually specify with @name

Approach 2: Adding @name (fails differently)

#' Extract a view from the vector
#' @name `[`
#' blah blah blah
#' @export
S7::method(`[`, cool_vector) <- function(x, i, ...) {
  x@vec[i]
}

which documents successfully but devtools::check() gives:

W  checking for missing documentation entries ...
 Undocumented code objects:
   ‘[’ ‘[<-’

Additionally examples fail

Error in check_subsettable(x) : S7 objects are not subsettable.

Reproducible example

Here is a complete reproducible example:

#' My class
#'
#' A test class for subsetting methods
#'
#' @param vec A vector
#' @return An object of class `cool_vector`
#' @export
cool_vector <- S7::new_class("cool_vector",
                             properties = list(
                               vec = S7::class_any
                             ))

#' Extract element from vector
#'
#' @param x A `cool_vector`
#' @param i The position to extract
#' @return vec[i]
#' @examples
#' cv <- cool_vector(1:10)
#' cv[5]
#' @export
S7::method(`[`, cool_vector) <- function(x, i, ...) {
  x@vec[i]
}

#' Replace element in vector
#'
#' @param x A `cool_vector`
#' @param i The position to replace
#' @param value Replacement value
#' @return Modified `cool_vector`
#' @examples
#' cv <- cool_vector(1:10)
#' cv[5] <- 100
#' @export
S7::method(`[<-`, cool_vector) <- function(x, i, ..., value) {
  x@vec[i] <- value
  x
}

I came to ask here as the vignette on developing packages requests that any questions on package development should be done here.

Also I think that this issue is different from the other issues open for roxygen2 requesting guidance on documenting the classes themselves as this refers to methods.

[mmaechler]

Roxygen is just a preprocessor for R's documentation format (in files man/*.Rd).
Is this a problem that Rd needs new syntax ?

• if yes, then it belongs here, and needs to be treated by the R core team eventually first
  such that only then, roxygen syntax can be extended and used to produce the then new Rd output
• otherwise, this is about a bug / missing feature(s) in roxygen2 (or also devtools ?).

[RodrigoZepeda]

Thank you for the answer.
My question is more general as in how do you document [ and [<-. Manually doing it (maybe I am doing it wrong) also doesn't work.

\name{cool_vector-subset}
\alias{[.cool_vector}     %Also tried \alias{[}
\alias{[<-.cool_vector}   %Also tried \alias{[<-}

\title{Extract or assign elements in a \code{cool_vector}}
\description{
  The `[` and `[<-` methods for `cool_vector` allow you to extract and replace elements, respectively.
}
\usage{
\method{[}{cool_vector}(x, i, \dots)                 

\method{[}{cool_vector}(x, i, \dots) <- value
}
\arguments{
  \item{x}{A \code{cool_vector} object.}
  \item{i}{Indices to select rows or elements.}
  \item{\dots}{Further arguments passed to or from other methods.}
  \item{value}{The replacement value for \code{[<-}.}
}
\value{
  For \code{[}: a subsetted \code{cool_vector} object.

  For \code{[<-}: The modified \code{cool_vector} object.
}
\examples{
# Example usage of \code{[}
cv <- cool_vector(1:10)
cv[5]
cv[5] <- 100
}
\keyword{methods}

with the NAMESPACE

export(cool_vector)
export("[.cool_vector") #Also tried exportMethods("[")
export("[<-.cool_vector") #Also tried exportMethods("[<-")

This also generates the error

Error in check_subsettable(x) : S7 objects are not subsettable.

when checking the examples.

[hadley]

The problem is that roxygen2 doesn't know about S7 yet, so isn't going to help you generate either the alias or the exports.

I also forget how you do this by hand, but I suspect you'll need something like:

#' @alias subset.{mypackage}
#' @exportS3method [ {mypackage}::cool_vector

You'll need to use class() on the S3 object to confirm what the exported class name should be (I forget the details but I know it includes the package name in order to automatically disambiguate classes)

[RodrigoZepeda]

Thank you for the answer.

I tried documenting as S3 methods as suggested, but unfortunately, that approach doesn't seem to work either. The roxygen approach throws an error when documenting: ✖ @exportS3Method must be used with a function. (which makes sense given the previous comments on roxygen being unaware of S7).

Doing it manually, on the other hand, requires something like this:

\name{subset.mypackage}
\alias{[.mypackage::cool_vector}
\alias{[<-.mypackage::cool_vector}
\title{Extract element from vector}
\usage{
\method{[}{`mypackage::cool_vector`}(x, i, ...)
\method{[}{`mypackage::cool_vector`}(x, i, ...) <- value
}

and a NAMESPACE with either

S3method("[", "mypackage::cool_vector")
S3method("[<-", "mypackage::cool_vector")

alternatively:

export("[.mypackage::cool_vector")
export("[<-.mypackage::cool_vector")

Either way, both generate the same warnings:

W  checking whether package ‘mypackage’ can be installed (1.3s)
   Found the following significant warnings:
     Warning: S3 methods ‘[.mypackage::cool_vector’, ‘[<-.mypackage::cool_vector’ were declared in NAMESPACE but not found
   See ‘/Users/.../mypackage.Rcheck/00install.out’ for details.
[...blah blah blah...]           
W  checking replacement functions ...
   Error in get(f, envir = code_env) : 
     object '[<-.mypackage::cool_vector' not found
   Calls: <Anonymous> -> Filter -> unlist -> lapply -> FUN -> get
   Execution halted
   The argument of a replacement function which corresponds to the right
   hand side must be named ‘value’.

This is beyond the scope of this issue, but the second warning is particularly intriguing as it seems to be a potential bug related to tools::checkReplaceFuns

Workaround

My current 'solution' is adding them directly to the onLoad:

.onLoad <- function(...) {
  S7::methods_register()

  S7::method(`[`, cool_vector) <- function(x, i, ...) {
    x@vec[i]
  }

  S7::method(`[<-`, cool_vector) <- function(x, i, ..., value) {
    x@vec[i] <- value
    x
  }
}

while at the same time documenting including them as S3 methods in the package:

`[.mypackage::cool_vector` <- function(x, i, ...){
  NextMethod()
}

`[<-.mypackage::cool_vector` <- function(x, i, ..., value){
  NextMethod()
}

But if there is a better suggestion I am happy to try.

[hadley]

Oh yeah, that makes sense, and definitely feels like a bug somewhere.

One possible solution would be for S7::methods_register() to also register S3 methods for you too.