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

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

由于勤奋而:我已经为"extract"方法找到了一个有用的例子。但是，对于我的问题来说，它似乎已经过时和不完整了。它在类文档中使用@slot标记，这是不(不再)支持的。它只显示了一个核心S4方法"["的扩展，而不是一个完整的Roxygen示例，包括S4泛型的文档。

如何正确记录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.

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

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

和构建包，我得到了功能文档。来自特定方法文档的任何标题都很尴尬地出现在"Description"字段中。因此，显然，roxygen2对每种方法的文档都做了一些修改，并且走在了正确的轨道上。然而，这还不足以避免来自

的大而令人不安的警告。

> R CMD check mypkgname

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

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

目前使用roxygen2的S4通用和S4方法文档的推荐方法是什么?
是否有一个很好的例子，显示完整的细节?
什么可能是原因，和解决方案，对大多数S4方法的文档丢失的警告(即使"丢失"文档的方法实际上有他们的文档解析由roxygen2和结果Rd文件至少是足够好的工作在R CMD build mypkgname之后的包)?

官方支持，详见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")
)

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

旧答案

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

为了记录S4泛型，我发现在大多数泛型头文件中都需要以下三行:

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

将helloworld-methods替换为the_name_of_your_generic-methods。这将是保存泛型及其所有方法的文档的Rd文件的名称。这种命名约定不是必需的，但很常见且很有用。@export标记现在是必需的，因为您的包需要一个名称空间，并且您希望该方法对包的用户可用，而不仅仅是包中的其他方法/函数。

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

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

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

下面是完整的示例。我构建了这个，它没有R CMD check testpkg的文档级警告，使用了最近的roxygen2开发版本的一个修复了错误的分支(我已经提供了)。为了在系统上快速安装这个分支，使用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问题来处理。

所以你的大部分文档工作都在通用定义上面的氧头中。这在代码中有一定的基础，因为泛型应该包括在任何随后定义的方法中出现的所有特定参数。请注意，在参数列表中作为...的一部分处理的参数不包括在内，也不应该特别记录，但是...本身也应该在泛型之上记录(参见下面的完整示例)。

关于文档功能基础的更多详细信息，有一个正在开发的wiki，旧的氧原子小插图，以及github上的氧原子2开发站点。关于Roxygen的R文档也有一个SO问题。

我已经找到了第(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)部分(最佳实践;(好的例子)仍然是开放的。

官方支持，详见devtools文档

旧答案

相关内容

最新更新

热门标签：