How to properly document S4 "[" and “[<-“ methods using roxygen?

Question

Below I posted a mini example in which I want do write documentation for an “[“ method for a S4 class. Does someone know how to properly document a method for the generic "[" using roxygen and S4?
I get a warning when checking the package after building (see below).

#' An S4 class that stores a string.
#' @slot a contains a string
#' @export
setClass("testClass", 
         representation(a="character"))

#' extract method for testClass
#'
#' @docType methods
#' @rdname extract-methods
setMethod("[", signature(x = "testClass", i = "ANY", j="ANY"),
         function (x, i, j, ..., drop){
             print("void function")
         }
)

Excerpt from package check:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
  generic '[' and siglist 'testClass'
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.
See the chapter 'Writing R documentation files' in manual 'Writing R Extensions'.

score 12 · Answer 1 · answered Dec 20 '10 at 18:37

I finally figured it out more or less. At least it works now:

#' An S4 class that stores a string.
#' @slot a contains a string
#' @export
setClass("testClass", 
     representation(a="character"))

#' extract parts of testClass
#'
#' @name [
#' @aliases [,testClass-method
#' @docType methods
#' @rdname extract-methods
#'
setMethod("[", signature(x = "testClass", i = "ANY", j="ANY"),
    function (x, i, j, ..., drop){
       print("void function")
    }
)

score 8 · Accepted Answer · answered Mar 23 '14 at 23:07

8

As of roxygen2 >3.0.0, you no longer need work arounds and only need:

#' Extract parts of testClass.
#'
setMethod("[", signature(x = "testClass", i = "ANY", j="ANY"),
  function (x, i, j, ..., drop){
    print("void function")
  }
)

answered Mar 23 '14 at 23:07

hadley

98,401
28
176
241

1

When I run this through roxygen2 4.0.1 I get the following from R CMD check: `WARNING Undocumented arguments in documentation object '[,testClass-method' 'j' '...' Functions with \usage entries need to have the appropriate \alias entries, and all their arguments documented.` – Alex Zvoleff Aug 02 '14 at 14:34
@azvoleff please submit a bug report with reproducible example at https://github.com/klutometis/roxygen/issues – hadley Aug 02 '14 at 16:26

score 8 · Answer 3 · answered Nov 08 '11 at 20:59

For what it's worth, in the case of a replacement function, you'll want something like the following:

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

#' extract parts of testClass
#'
#' @name [
#' @aliases [,testClass-method
#' @docType methods
#' @rdname extract-methods
setMethod("[", signature(x = "testClass", i = "ANY", j="ANY"),
  function (x, i, j, ..., drop) {
     x@a[i]
  }
)

#' replace names of testClass
#'
#' @name [
#' @aliases [<-,testClass-method
#' @docType methods
#' @rdname extract-methods
setReplaceMethod("names", signature(x = "testClass", value = "ANY"), definition = function (x, value) {
  names(x@a) <- value
  x
})

Great thanks, @name is key here, otherwise you get `missing name in block` error. That solves the problem. — Matt Bannert, Sep 03 '13 at 09:39

How to properly document S4 "[" and “[<-“ methods using roxygen?

3 Answers3

Linked