如何正确地记录S4类插槽使用Roxygen2？ [英] How to properly document S4 class slots using Roxygen2?

问题描述

对于使用roxygen（2）记录类，指定标题和描述/细节看起来与函数，方法，数据等相同。然而，槽和继承是他们自己的动物。

尽职调查：

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

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

 ＃'我的S4类的标题，扩展\code {character}类。 
＃'
＃'关于这个类的一些细节和我在体内的计划。 
＃'
＃'\describe {
＃'\item {myslot1} {一个合乎逻辑的跟踪某事。} 
＃'
＃ \\item {myslot2} {一个指定其他内容的整数。} 
＃'
＃'\item {myslot3} {一个data.frame包含一些数据} 
＃'} 
＃'@name mynewclass-class 
＃'@rdname mynewclass-class 
＃'@exportClass mynewclass 
 setClass（mynewclass，
 representation（myslot1 =logical ，
 myslot2 =integer，
 myslot3 =data.frame），
 contains =character
）
  

但是，虽然这样，这个 \describe ， \item 用于记录插槽的方法似乎与roxygen（2）的其余部分不一致，因为没有 @ -delimited标记和插槽可以无记录没有从 roxygenize（）的反对。它也没有说明一个一致的方式来记录被定义的类的继承。我想通过使用 @import 标签，依赖依然一般工作正常（如果一个特定的插槽需要一个非基类从另一个包）。

因此，总结一下，目前roxygen（2）插槽的最佳实践是什么？

似乎是目前三个选项：

• A- - 列表（如上所示） 。


• B - @slot ...但是有额外的标签/实现我错过了。我不能得到@slot使用roxygen / roxygen2在
  的版本，它被包括作为替换的示例
  上面的逐项列表。再次，上面的示例使用roxygen（2）。


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

我从一个帖子借用/扩展这个问题到 roxygen2 开发页面上 github 。

解决方案

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

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

以前

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

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

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

For documenting classes with roxygen(2), specifying a title and description/details appears to be the same as for functions, methods, data, etc. However, slots and inheritance are their own sort of animal. What is the best practice -- current or planned -- for documenting S4 classes in roxygen2?

Due Diligence:

I found mention of an @slot tag in early descriptions of roxygen. A 2008 R-forge mailing list post seems to indicate that this is dead, and there is no support for @slot in roxygen:

Is this true of roxygen2? The previously-mentioned post suggests a user should instead make their own itemized list with LaTeX markup. E.g. a new S4 class that extends the "character" class would be coded and documented like this:

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

However, although this works, this \describe , \item approach for documenting the slots seems inconsistent with the rest of roxygen(2), in that there are no @-delimited tags and slots could go undocumented with no objection from roxygenize(). It also says nothing about a consistent way to document inheritance of the class being defined. I imagine dependency still generally works fine (if a particular slot requires a non-base class from another package) using the @import tag.

So, to summarize, what is the current best-practice for roxygen(2) slots?

There seem to be three options to consider at the moment:

• A -- Itemized list (as example above).
• B -- @slot ... but with extra tags/implementation I missed. I was unable to get @slot to work with roxygen / roxygen2 in versions where it was included as a replacement for the itemized list in the example above. Again, the example above does work with roxygen(2).
• C -- Some alternative tag for specifying slots, like @param, that would accomplish the same thing.

I'm borrowing/extending this question from a post I made to the roxygen2 development page on github.

解决方案

roxygen2 v4.1+ and Hadley's latest doc for doing this:

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

I have not tried it yet for RC, but it works for me for S4 now.

Previously

It looks like S4 class slots are fully supported under Roxygen2 version 3.0+:

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

"document your S4 classes, S4 methods and RC classes with roxygen2 – you can safely remove workarounds that used @alias and @usage, and simply rely on roxygen2 to do the right thing."

这篇关于如何正确地记录S4类插槽使用Roxygen2？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！