如何使用roxygen2正确loggingS4方法
我已经在SO和其他地方看到了一些关于Roxygen2未来版本应该如何实现的讨论。 但是，我卡住了。 我应该如何使用Roxygen2来logging一个S4generics以及它的方法？ 一个全新的通用/方法的工作示例，以及扩展基本S4通用的例子将是非常有用的。 我不想为同一个通用的每个S4方法做单独的（大部分）冗余文档。
尽职调查：我已经find了“提取”方法的一个有用的例子。 但是，我的问题似乎已经过时和不完整。 它在类文档中使用@slot标签，不支持（不再支持）。 它只显示了核心S4方法的扩展“[”，而不是一个完整的Roxygen例子，包括S4通用的文档。
如何正确loggingS4“[”和“[< – ”使用roxygen的方法？
如果我完整地logging了一个带有标题的新的S4generics，描述@param @return @name @aliases @docType @rdname ，然后用相应的@name @aliases @docType @rdnameloggingS4方法，我得到下面的R CMD check警告：
* checking for missing documentation entries ... WARNING Undocumented S4 methods: << long list of apparently undocumented methods. Eg generic 'plot' and siglist 'myClass1,ANY' >> All user-level objects in a package (including S4 classes and methods) should have documentation entries.
它首先看起来好像没有用这种方式logging的使用roxygen2的S4方法实际上工作。 但是，到目前为止，我已经注意到，我的核心方法“show”的扩展没有相关的错误，尽pipe它们的logging方式与其余部分完全相同。 下面是一个展示方法之上的完整roxygen文档的例子，它没有生成missing-documentation错误：
#' @name show #' @aliases show,myClass2-method #' @docType methods #' @rdname show-methods
因此，我不知所措。 正如你所看到的，我已经包含了在R包手册的S4文档部分中描述的用于S4方法的别名约定，即方法应该有一个别名，并且具有下面的名字（没有空格）：
generic,signature_list-method.
不知何故， R CMD check并不能完全理解这一点。
最后，使用以下命令构build文档之后：
library("devtools") library("roxygen2") document("mypkgname") check_doc("mypkgname")
并build立包，我得到function的文件。 来自特定方法文档的任何标题都会出现在“描述”字段中，而不是很笨拙。 所以roxygen2显然对每个方法的文档做了一些事情，并且是正确的。 但是，仅仅避免一个大的麻烦警告是不够的
> R CMD check mypkgname
我已经看过了Rd文件，但是我对它们的了解甚less，很快就看不出是什么问题了，反正我想知道roxygen2解决scheme，这样我就不必在每次文档修改之后直接操作Rd文件。
所以这是一个多部分的问题：
-
现在推荐使用roxygen2的S4通用和S4方法文档的方法是什么？
-
有没有一个很好的例子可以显示完整的细节？
-
可能的原因和解决办法是警告大多数S4方法的文档缺失（尽pipe“missing”文档的方法实际上是由roxygen2parsing了他们的文档，并且生成的Rd文件至less可以工作在
R CMD build mypkgname之后打包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") )
上面的链接非常清楚地解释了通过roxygen / devtools支持S3，S4和RC。 这里的解释应该被认为取代了下面的旧的答案，现在确实有效，但是不那么清晰和复杂。
旧的答案
这是一个适用于大多数S4方法的例子。
为了loggingS4generics，我在大多数通用头文件中find以下三行：
#' @export #' @docType methods #' @rdname helloworld-methods
helloworld-methods被replace为the_name_of_your_generic-methods 。 这将是Rd文件的名称，该文件保存generics及其所有方法的文档。 这个命名约定不是必须的，但是通用和有用的。 @export标记是必需的，因为你的包需要一个命名空间，你希望这个方法对你的包的用户是可用的，而不是你的包中的其他方法/函数。
对于logging方法，我发现只需要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被添加到其他方法的别名标签中，即使它们的签名定义只有一个元素。
一个完整的例子如下。 我build立了这个工具，它没有R CMD check testpkg文档级别的警告，使用了一个最新版本的roxygen2（我已经可用）的bug修复fork 。 为了在你的系统上快速安装这个fork，使用library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") 。 由于报价错误（在单独的答案中描述），最新版本的roxygen2将无法正常工作，但是我期望这个function很快就会被合并，而且我的分支将不是必需的。 为了在一个包的其余部分看到这个例子，并且看到了最终的文档（Rd）文件，我把它作为一个简单的testing包在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问题来处理。
因此，大部分文档工作都会放在generics定义之上的roxygen头文件中。 这在代码中有一些基础，因为generics应该包含出现在随后定义的任何方法中的所有特定参数。 请注意，作为参数列表中的一部分进行处理的参数不包含在内，不应该特别logging，但是...本身也应该logging在generics之上（参见下面的完整示例）。
有关loggingfunction基础知识的更多详细信息，有一个正在进行的维基 ， 旧的roxygen小插曲 ，以及github上的roxygen2开发网站 。 一般来说Roxygen也有关于R文档的SO问题 。
我已经追踪到第（3）部分的答案–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）（最佳实践，很好的例子）仍然是公开的。
