如何使用roxygen正确记录S4“ [”和“ [< -”方法？

Question

以下是我发布的一个小例子，我想为S4类的"["方法编写文档。有人知道如何使用roxygen和S4正确地记录通用方法"["的方法吗？
在构建后检查包时，我收到了警告（如下所示）。

#' 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")
         }
)

摘自包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'.

- Mark Heckmann

Answer 1

我最终想出了更或多或少的解决方法。至少现在它可以工作：

#' 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")
    }
)

- Mark Heckmann

Answer 2

如果是替换函数，你需要像下面这样：

#' 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
})

- Max Gasner

---

非常感谢，@name 在这里是关键，否则会出现“块中缺少名称”的错误。这解决了问题。 - Matt Bannert

Answer 3

从roxygen2 >3.0.0开始，您不再需要解决问题，只需要：

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

- hadley

---

当我将这个通过roxygen2 4.0.1运行时，从R CMD检查获得以下警告： “警告：文档对象'[，testClass方法]'中有未记录的参数'j''...'。具有\usage条目的函数需要有适当的\alias条目，并且需要记录所有参数。” - Alex Zvoleff

@azvoleff 请在 https://github.com/klutometis/roxygen/issues 提交带有可重现示例的错误报告。 - hadley