首页 文章

如何使用Roxygen2正确记录S4类槽？

提问于
浏览 次
297

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

尽职调查：

我在早期的roxygen描述中发现了一个 @slot 标签 . A 2008 R-forge mailing list post似乎表明这已经死了，并且在roxygen中没有对 @slot 的支持：

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

然而，虽然这有效，但是这种用于记录插槽的方法似乎与其余的roxygen（2）不一致，因为没有 @ -delimited标签和插槽可以没有记录，而且没有来自 roxygenize() 的反对意见 . 它也没有说明一致的方法来记录正在定义的类的继承 . 我想依赖仍然通常使用 @import 标记工作正常（如果特定插槽需要来自另一个包的非基类） .

总而言之，目前roxygen（2）槽的最佳实践是什么？

目前似乎有三种选择：

A - 分项列表（如上例所示） . B - @slot ...但是有额外的标签/实施我错过了 . 我无法让@slot在版本中使用roxygen / roxygen2作为上述示例中逐项列表的替代 . 同样，上面的例子确实适用于roxygen（2） . C - 用于指定插槽的替代标记，如@param，可以完成相同的操作 .

我在github的 roxygen2 开发页面上发布的帖子中借用/扩展了这个问题 .

class r s4 slot roxygen2

3 回答

  • 27

    roxygen2 v4.1和Hadley的最新文档：

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

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

    以前

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

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

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

    回复于
  • 18

    Updated answer for Roxygen2 5.0.1, current as of 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

    Updated answer for Roygen2 3.0.0, current as of 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

    回复于
  • 14

    如果您要在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
    回复于

相关问题