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

Question

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

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

如何正确记录S4“[”和“[< - ”方法使用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”的扩展没有相关的错误，即使它们的记录方式与其他方法完全相同。 以下是我在其中一个show方法中包含的完整roxygen文档的示例，它没有生成遗漏文档错误：

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

因此，我很茫然。 如您所见，我已经包含了R包手册的S4文档部分中描述的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 doc中解释

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标记现在是必需的，因为包需要一个命名空间，并且您希望包的用户可以使用此方法，而不仅仅是包中的其他方法/函数。

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

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

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

完整的例子如下。 我构建了这个并且没有来自R CMD check testpkg文档级警告，使用了最近开发的roxygen2版本（我已经提供）的错误修复分支 。 要在系统上快速安装此fork，请使用library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") 。 由于引用错误（在单独的答案中描述），最新版本的roxygen2目前无法正常工作，但我希望这很快就会合并，而且我的fork不是必需的。 为了在包的其余部分的上下文中查看此示例，并查看生成的文档（Rd）文件，我将其作为一个名为testpkg的 github上的普通测试包提供。

##############################################################
#' 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标头。 这在代码中有一些基础，因为泛型应包括出现在任何后续定义的方法中的所有特定参数。 请注意，作为的一部分进行处理参数...参数列表中不包含和不应该被明确记载，但...本身应该高于一般被记录，以及（请参见下面的完整的例子）。

有关记录函数基础知识的更多详细信息，有一个正在进行的维基 ， 旧的roxygen vignette ，以及github上的roxygen2开发站点 。 关于R一般的Rxygen文档也有一个问题 。

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）（最佳实践;良好的例子）仍然是开放的。