如何使用Roxygen2正确记录S4类别的slots？

Question

对于使用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中使用@slot。同样，上面的示例可以在roxygen(2)中正常工作。
• C -- 指定插槽的某些替代标记，例如@param，可以实现相同的功能。

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

- Paul 'Joey' McMurdie

---

@slot 可能是你长期想要的，但需要首先实现它... - hadley

谢谢！这很好知道。我很高兴我的代码使用的setClass语句比setMethod要少得多。一旦实现了@slot，进行更改就不会太痛苦。 - Paul 'Joey' McMurdie

一些关于@slot的讨论：https://github.com/klutometis/roxygen/pull/85 - Brian Diggs

相关问题：https://dev59.com/CWvXa4cB1Zd3GeqPJ4JB - Joris Meys

S4类现在在Roxygen2版本3中得到了完全支持（可在github上获取）。 - Gregor Thomas

Answer 1

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

- William Entriken

---

您是否使用过@Brian Diggs的实现？它有效吗？您认为您能提供一些有关该方法的细节（从而类似于@slot解决方案）。我还没有尝试过它，正在等待（也许是懒惰地等待）这个未决的@slot解决方案。我知道这不是问题的提出方式，但基于评论（包括@hadley的评论），似乎@slot才是“真正”的答案。我同意您的评估，即列出项目清单（就像我的问题中那样）是当前最佳实践，但希望很快被替换掉。 - Paul 'Joey' McMurdie

Answer 2

如果您希望在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

- Joris Meys

Answer 3

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

- Paul 'Joey' McMurdie

---

@slot 可以完美地使用，您还可以使用它（或 @field）来伪造文档化 S3 类。 - Brandon Bertelsen