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”的扩展没有相关的错误，即使它们的记录方式与其他方法完全相同。以下是我在其中一个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文件了。文件修订。

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

对于使用roxygen2的S4通用和S4方法文档，目前推荐的方法是什么？
是否有一个显示完整细节的好例子？
对于大多数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语句应与通用语句完全匹配。 @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目前无法正常工作，但我希望这很快就会合并，而且我的fork不是必需的。为了在包的其余部分的上下文中查看此示例，并查看生成的文档（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）（最佳实践;很好的例子）仍然是开放的。

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

2 个答案:

官方支持，在devtools doc

旧答案