如何使用Roxygen2正确地记录S4类插槽?

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

尽职调查:

我发现在roxygen的早期描述中提到了@slot标签。 2008年R-forge邮件列表帖子似乎表明这已经死了，并且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"
)

然而，尽管这样做是有效的，但是这种用于记录槽的\describe， \item方法似乎与roxygen(2)的其余部分不一致，因为没有@-分隔的标记，并且槽可以在没有roxygenize()反对的情况下被记录。它也没有说明以一致的方式记录所定义类的继承。我认为使用@import标记依赖关系通常仍然可以正常工作(如果特定插槽需要来自另一个包的非基类)。

那么，总结一下，目前roxygen(2)插槽的最佳实践是什么?

目前似乎有三种选择可供考虑:

A——分项列表(如上面的例子)。 B——@槽…但是我错过了额外的标签/实现。我无法让@slot在版本中使用roxygen / roxygen2 它是作为示例中逐项列表的替换而包含的以上。同样，上述例子也适用于roxygen(2)。 C——一些用于指定槽的替代标记，比如@param，可以完成同样的事情。

我从github上roxygen2开发页面上的一篇文章中借用/扩展了这个问题。

当前回答

Full Decent提供的解决方案是OK的，如果你想在Rd文件中记录槽本身。当使用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-09 13:49:10

其他回答

Full Decent提供的解决方案是OK的，如果你想在Rd文件中记录槽本身。当使用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-09 13:49:10

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来做正确的事情。”

2013-12-10 01:01:08

Roxygen2 5.0.1的更新答案，目前为7.2.0

对于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-08 21:53:04

如何使用Roxygen2正确地记录S4类插槽?

推荐文章

最新文章

标签