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

Question

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

62

我在stackoverflow和其他地方看到了一些关于如何使用Roxygen2记录S4通用函数及其方法的讨论。然而，我卡住了。我应该如何使用Roxygen2记录S4通用函数以及它的方法？一个全新的通用函数/方法的工作示例以及扩展基本S4通用函数的示例将非常有用。我不想为同一个通用函数的每个S4方法制作单独的（大部分是）冗余文档。

尽职调查：我找到了一个有用的"extract"方法示例。但是对我的问题来说，它似乎已经过时并且不完整。它在类文档中使用了@slot标签，这个标签现在似乎不再被支持。它只显示了一个核心S4方法“[”的扩展，而没有包括完整的Roxygen示例，包括S4通用函数的文档。

如何使用Roxygen正确记录S4 "[ ]"和"[<-"方法?

如果我完全使用标题、描述、@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 方法别名约定，即方法应该有一个以下名称的别名（不带空格）：R 手册中的 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包中使用），可能的原因和解决方案是什么？

- Paul 'Joey' McMurdie

2个回答

9

我已经找到了第三部分的答案——S4方法不那么缺失的文档——是因为在使用S4命名约定时错误地在\alias标签周围添加引号，很可能是由于包含逗号作为名称一部分的别名的文本处理导致的错误。这仍然适用于此发布时roxygen2的最新版本。我在roxygen2 github页面上发布了一个更详细的bug描述和可重现的示例。

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

简言之，

#' @aliases show,helloworld-method

变成

\alias{"show,helloworld-method"}

在生成的Rd文件中。去掉引号可以消除“R CMD check”警告，并且文档在两种情况下都可以构建和正常工作。

我认为这个问题的部分（1）和（2）（最佳实践；良好示例）仍然是开放的。

- Paul 'Joey' McMurdie

1

这个问题之前已经被yihui在一些以前的问题帖子中提到过：24和29。 - Paul 'Joey' McMurdie

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Paul 'Joey' McMurdie · Accepted Answer

官方支持，在开发工具文档中解释

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 标记必须遵守编写 R 扩展官方 S4 文档部分中描述的命名约定。

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

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

以下是完整的示例。我构建了这个示例，并且使用已提供的修复错误的roxygen2非常新的devel版本的分支，从R CMD check testpkg没有文档级警告。要快速在您的系统上安装此分支，请使用library("devtools"); install_github("roxygen", "joey711")。最近的roxygen2版本由于引号错误（在另一个答案中描述）而无法使用，但我希望这很快就会被纳入，我的分支将不再必要。要查看此示例与软件包其余部分的上下文，并查看生成的文档（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标题中。这在代码中有一定的基础，因为通用应该包括所有后续定义的方法中出现的特定参数。请注意，在参数列表中作为...的一部分处理的参数不包括在内，并且不应该具体记录，但是...本身也应该在通用上面记录（请参见下面的完整示例）。

有关记录函数基础知识的更多详细信息，请参见正在进行中的wiki，旧的roxygen手册以及github上的roxygen2开发网站。还有一个关于Roxygen的R文档的SO问题。