提问



对于使用roxygen(2)记录类,指定标题和描述/细节看起来与函数,方法,数据等相同。但是,插槽和继承是它们自己的动物类型。在roxygen2中记录S4类的最佳实践 - 当前或计划的最佳实践是什么?


尽职调查:


我在早期的roxygen描述中发现了@slot标签。
2008年R-forge邮件列表帖子
似乎表明这已经死了,
在[[ro]]中没有@slot的支持:[24]


roxygen2是真的吗?前面提到的帖子建议用户应该使用LaTeX标记创建自己的逐项列表。例如。扩展"character"类的新S4类将被编码并记录如下:


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


然而,虽然这有效,但\describe\item用于记录插槽的方法似乎与其余的roxygen(2)不一致,因为没有@ - 分隔的标签和插槽可以没有人反对roxygenize()。它也没有说明记录正在定义的类的继承的一致方法。我想通过使用@import标签,依赖仍然可以正常工作(如果特定插槽需要来自另一个包的非基类)。


总而言之,目前roxygen(2)槽的最佳实践是什么?


目前似乎有三种选择:



  

      
  • A - 分项清单(如上例所示)。

  •   
  • B - @slot ...但是有额外的标签/实施我错过了。我无法让@slot在版本中使用roxygen/roxygen2
      它被包含作为示例中的逐项列表的替代
      以上。同样,上面的例子确实适用于roxygen(2)。

  •   
  • C - 用于指定插槽的替代标记,如@param,可以完成相同的操作。

  •   



我是从github上的roxygen2开发页面上的帖子中借用/扩展这个问题。[25]

最佳参考


更新了Roxygen2 5.0.1的答案,目前为6.0.1


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


#' 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[26]


更新了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"}.}
#'    }
#'  }


这与作为对象内部列表的槽的内部表示一致。正如您所指出的,这种语法与其他行不同,我们可能希望将来有一个更强大的解决方案,它包含了继承知识 - 但今天却不存在。


正如@Brian Diggs指出的那样,这个功能被拉到3.0.0,进一步的讨论在https://github.com/klutometis/roxygen/pull/85 [27]

其它参考1


如果您要在Rd文件中记录插槽,那么Full Decent提供的解决方案是可以的。使用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

其它参考2


roxygen2 v4.1 +和Hadley的最新文档:



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


我还没有尝试过RC,但它现在适用于S4。


以前



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


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


使用roxygen2记录您的S4类,S4方法和RC类 - 您可以安全地删除使用@alias@usage的变通方法,并且只需依靠roxygen2来做正确的事情。