如何使用Roxygen2正确loggingS4类插槽?

为了用roxygen(2)logging类,指定标题和描述/细节看起来与函数,方法,数据等相同。然而,插槽和inheritance是它们自己的一种动物。 目前或计划的最佳做法是如何loggingroxygen2中的S4课程?

尽职调查:

我在早期的roxygen描述中发现了一个@slot标签。 2008 R-forge邮件列表post似乎表明这已经死了,并且在@slot中不支持@slot:

roxygen2是真的吗? 前面提到的postbuild议用户应该用LaTeX标记制作自己的分项列表。 例如,扩展"character"类的新的S4类将被编码和logging如下:

 #' The title for my S4 class that extends \code{"character"} class. #' #' Some details about this class and my plans for it in the body. #' #' \describe{ #' \item{myslot1}{A logical keeping track of something.} #' #' \item{myslot2}{An integer specifying something else.} #' #' \item{myslot3}{A data.frame holding some data.} #' } #' @name mynewclass-class #' @rdname mynewclass-class #' @exportClass mynewclass setClass("mynewclass", representation(myslot1="logical", myslot2="integer", myslot3="data.frame"), contains = "character" ) 

然而,虽然这是有效的,但是这个\describelogging槽的\item方法看起来与roxygen(2)的其余部分不一致,因为没有@ -delimited标记,并且槽可以在没有来自roxygenize()反对的情况下无证。 它也没有提到一个一致的方式来logging所定义类的inheritance。 我想依赖仍然一般工作正常(如果一个特定的插槽需要从另一个包的非基类)使用@import标记。

因此,总结一下,roxygen(2)插槽目前的最佳做法是什么?

目前似乎有三个select需要考虑:

  • A – 分项清单(如上所示)。
  • B – @slot …但额外的标签/执行我错过了。 我无法使用@slot与roxygen / roxygen2一起使用,在上面的示例中,它包含了作为条目列表的替代品的版本。 再次,上面的例子与roxygen(2)一起工作。
  • C – 指定插槽的一些替代标签,如@param ,可以完成同样的事情。

我借用/扩展了这个问题,从我发布到github上的roxygen2开发页面。

Roxygen2 5.0.1的更新回答,目前为6.0.1

对于S4,现在最好的做法是使用@slot标签进行logging:

 #' The title for my S4 class that extends \code{"character"} class. #' #' Some details about this class and my plans for it in the body. #' #' @slot myslot1 A logical keeping track of something. #' @slot myslot2 An integer specifying something else. #' @slot myslot3 A data.frame holding some data. #' #' @name mynewclass-class #' @rdname mynewclass-class #' @export 

在旁注中, @exportClass仅在某些情况下是必需的,导出函数的一般方法是使用@export 。 除非您希望其他软件包能够扩展课程,否则您也不必导出课程。

另见http://r-pkgs.had.co.nz/namespace.html#exports

更新了Roygen2 3.0.0的答案,目前为5.​​0.1。

对于S4,最好的做法是以下格式的文件:

 #' \section{Slots}{ #' \describe{ #' \item{\code{a}:}{Object of class \code{"numeric"}.} #' \item{\code{b}:}{Object of class \code{"character"}.} #' } #' } 

这与插槽内部表示forms在对象内部一致。 正如你指出的那样,这个语法与其他语言不同,我们可能希望在将来能够结合inheritance知识的更强大的解决scheme – 但是现在还不存在。

正如@Brian Diggs指出的那样,这个特性被拉进3.0.0,在https://github.com/klutometis/roxygen/pull/85

如果您要loggingRd文件本身中的插槽,则FullDecent提供的解决scheme是可以的。 使用roxygen2 ,可以使用标签@section\describe基本相同。 一个例子:

 #' The EXAMPLE class #' #' This class contains an example. This line goes into the description #' #' This line and the next ones go into the details. #' This line thus appears in the details as well. #' #'@section Slots: #' \describe{ #' \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1} #' \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.} #' } #' #' @note You can still add notes #' @name EXAMPLE #' @rdname EXAMPLE #' @aliases EXAMPLE-class #' @exportClass EXAMPLE #' @author Joris Meys 

roxygen2 v4.1 +和哈德利最新的文档为此:

http://r-pkgs.had.co.nz/man.html#man-classes

我还没有尝试过RC,但现在对我来说S4是有效的。

先前

它看起来像S4类插槽Roxygen2版本3.0+完全支持:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

“使用roxygen2logging你的S4课程,S4方法和RC课程 – 你可以安全地移除使用@alias@usage解决方法,并简单地依靠roxygen2来做正确的事情。