如何使用 roxygen2 正确记录 S4 方法

Question

我在 SO 和其他地方看到了一些关于在 Roxygen2 的未来版本中应该或将如何完成的讨论。但是，我被困住了。我应该如何使用 Roxygen2 记录 S4 泛型及其方法？全新泛型/方法的工作示例以及扩展基本 S4 泛型的示例将非常有用。我不想为相同泛型的每个 S4 方法制作单独的（大部分）冗余文档。

尽职调查： 我已经为“提取”方法找到了一个有用的例子。但是，对于我的问题，它似乎已经过时且不完整。它在类文档中使用 @slot 标记，该标记不再（不再？）支持。它仅显示核心 S4 方法“[”的扩展，而不是包含 S4 泛型文档的完整 Roxygen 示例。

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

如果我用标题、描述 @param @return @name @aliases @docType @rdname 完整记录一个新的 S4 泛型，然后只用相应的 @name @aliases @docType @rdname 记录 S4 方法，我会收到以下 R CMD check 警告：

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

乍一看，好像我用 roxygen2 以这种方式记录的 S4 方法都没有真正起作用。然而，到目前为止，我注意到我的核心方法“show”的扩展没有相关的错误，即使它们的记录方式与其他方法完全相同。这是我在其中一种显示方法上方包含的完整 roxygen 文档的示例，它没有生成缺少文档的错误：

#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods

因此，我不知所措。如您所见，我已经包含了the S4 documentation section of the R package manual 中描述的 S4 方法的别名约定，即方法应该有一个具有以下名称的别名（不带空格）：

generic,signature_list-method.

不知何故，R CMD check 并没有完全理解这一点。

最后，在构建文档后使用：

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

并构建包，我得到了功能文档。特定方法文档中的任何标题都会出现在“描述”字段中，相当尴尬。所以 roxygen2 显然对每个方法的文档做了一些事情，并且走上了正确的轨道。然而，仅仅避免来自

的大而令人不安的警告是不够的

> R CMD check mypkgname

我查看了 Rd 文件，但我对它们的了解甚至更少，无法快速了解问题所在，而且我无论如何都想知道 roxygen2 解决方案，这样我就不必在每次操作后直接操作 Rd 文件文档修订。

所以这是一个多部分的问题：

1. 对于使用 roxygen2 的 S4 泛型和 S4 方法文档，目前推荐的方法是什么？

2. 在某个地方是否有一个很好的示例可以显示完整的详细信息？

3. 大多数 S4 方法的文档丢失的警告可能是什么原因和解决方案（即使具有“缺少”文档的方法实际上已经由 roxygen2 解析了它们的文档并且生成的 Rd 文件是至少足以在 R CMD build mypkgname 之后的包中工作？

Answer 1

官方支持，在 devtools 文档中解释

http://r-pkgs.had.co.nz/man.html#man-classes （向下滚动到 S4 小节）。

该页面的当前简短示例复制如下（为方便起见）：

#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

上面的链接非常清楚地解释了通过 roxygen/devtools 对 S3、S4 和 RC 的支持。应该考虑那里的解释取代下面较旧的答案，该答案目前确实有效，但不太清楚且更复杂。

旧答案

这是一个适用于大多数 S4 方法的示例。

为了记录 S4 泛型，我发现在我的大多数泛型标题中需要以下三行：

#' @export
#' @docType methods
#' @rdname helloworld-methods

其中helloworld-methods 替换为the_name_of_your_generic-methods。这将是包含泛型及其所有方法的文档的 Rd 文件的名称。此命名约定不是必需的，但常见且有用。 @export 标签是必需的，因为您的包需要命名空间，并且您希望此方法可供包的用户使用，而不仅仅是包中的其他方法/功能。

对于记录方法，我发现只需要两行，提供@rdname 和@aliases 标记。 @rdname 语句应该与泛型的语句完全匹配。 @aliases 标记必须遵守Writing R Extensions 的官方 S4 文档部分中描述的命名约定。

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method

@aliases 名称中的逗号后不应有空格。我不知道何时将,ANY 添加到签名列表末尾的确切规则。模式似乎是所有@aliases签名列表中的元素数量需要与方法中最长的签名向量中的元素数量相匹配。在下面的示例中，其中一个方法是使用 2 元素签名定义的，因此 R CMD check 对文档不满意，除非将 ,ANY 添加到其他方法的别名标记中，即使它们的签名定义仅有一个元素。

下面是一个完整的例子。我构建了这个，它使用bug-fixed fork of a very recent devel version of roxygen2 (which I have made available)，没有来自R CMD check testpkg 的文档级警告。要在您的系统上快速安装此 fork，请使用 library("devtools"); install_github("roxygen", "joey711")。由于引用错误（在单独的答案中描述），最新版本的 roxygen2 此刻无法工作，但我希望这将很快被合并，我的叉子将不是必需的。为了在包的其余部分的上下文中查看这个示例，并查看生成的文档 (Rd) 文件，我在 github 上将它作为一个简单的测试包提供，称为 testpkg。

##############################################################
#' The title, in this case: Helloworld-ify the argument.
#'
#' Some additional details about this S4 generic and its methods.
#' The extra blank line between this section and the title is
#' critical for roxygen2 to differentiate the title from the
#' description section.
#'
#' @param x Description of \code{x}. The main argument in this
#'  example. Most often has such and such properties.
#'
#' @param y Description of \code{y}. An argument that is rarely
#'  used by \code{"helloworld"} methods. 
#'
#' @param ... Additional argument list that might not ever
#'  be used.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#' 
#' @seealso \code{\link{print}} and \code{\link{cat}}
#' 
#' @export
#' @docType methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
#' helloworld(char2helloworld("thisismystring"))
#' helloworld(matrix(0,3,3))
#' helloworld(list(0,0,0))
#' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
    cat("Hello World!")
    cat("\n")
    standardGeneric("helloworld")
})

#' @rdname helloworld-methods
#' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
    cat(class(x))
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
    show(x)
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
    show(x)
})

此示例假定您不需要单独的特定于方法的文档，因为您的方法并未完全偏离基于通用文档所期望的行为。 roxygen2 中有一些方法可以使用@usage 标签来处理这种替代情况，但细节最好由单独的 SO 问题处理。

因此，您的大部分文档工作都放在通用定义上方的 roxygen 标头中。这在代码中有一些基础，因为泛型应该包括出现在任何随后定义的方法中的所有特定参数。请注意，作为参数列表中... 的一部分处理的参数不包括在内，也不应专门记录，但... 本身也应记录在泛型之上（请参阅下面的完整示例）。

有关记录函数基础知识的更多详细信息，请参阅wiki in progress、old roxygen vignette 和 roxygen2 development site on github。一般还有SO question on R documentation with Roxygen。

Answer 2

我发现第 (3) 部分的答案——S4 方法的不那么缺失的文档——是因为使用 S4 命名约定时在 \alias 标记周围错误地添加了引号；很可能是由于对包含逗号作为其名称一部分的别名进行文本处理而导致的错误。在本文发布时，最新版本的 roxygen2 仍然如此。我刚刚在 roxygen2 github 页面上通过一个可重现的示例发布了对该错误的更全面的描述：

https://github.com/klutometis/roxygen/issues/40

简单地说，

#' @aliases show,helloworld-method

变成

\alias{"show,helloworld-method"}

在生成的 Rd 文件中。删除引号会删除 R CMD check 警告，并且文档会在这两种情况下构建并正常运行。

我认为这个问题的第 (1) 和 (2) 部分（最佳实践；良好示例）仍然存在问题。