312

对于使用 roxygen(2) 记录类，指定标题和描述/细节似乎与函数、方法、数据等相同。但是，插槽和继承是它们自己的一种动物。在 roxygen2 中记录 S4 类的最佳实践是什么（当前的或计划的）？

尽职调查：

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

roxygen2 是这样吗？前面提到的帖子建议用户应该使用 LaTeX 标记制作自己的逐项列表。例如，扩展该类的新 S4 类"character"将被编码和记录如下：

#' 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，可以完成同样的事情。

我正在从我在githubroxygen2上的开发页面上发表的帖子中借用/扩展这个问题。

4

3 回答 3

31

更新了 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

更新了 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进一步讨论

于 2012-06-08T21:53:04.203 回答
20

如果您要在 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
于 2013-01-09T13:49:10.937 回答
16

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 类——您可以安全地删除使用@aliasand的变通方法@usage，并简单地依靠 roxygen2 来做正确的事情。”

于 2013-12-10T01:01:08.047 回答