[英]How to properly document S4 class slots using 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. 对于使用roxygen(2)记录类,指定标题和描述/细节似乎与函数,方法,数据等相同。但是,插槽和继承是它们自己的动物类型。 What is the best practice -- current or planned -- for documenting S4 classes in roxygen2?
在roxygen2中记录S4类的最佳实践 - 当前或计划的最佳实践是什么?
Due Diligence: 尽职调查:
I found mention of an @slot
tag in early descriptions of roxygen. 我在早期的roxygen描述中发现了一个
@slot
标签。 A 2008 R-forge mailing list post seems to indicate that this is dead, and there is no support for @slot
in roxygen: 2008年的R-forge邮件列表帖子似乎表明这已经死了,而且
@slot
在roxygen中没有支持:
Is this true of roxygen2? roxygen2是真的吗? The previously-mentioned post suggests a user should instead make their own itemized list with LaTeX markup.
前面提到的帖子建议用户应该使用LaTeX标记创建自己的逐项列表。 Eg a new S4 class that extends the
"character"
class would be coded and documented like this: 例如,扩展
"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"
)
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()
. 然而,尽管这个作品,这个
\\describe
, \\item
用于记录的插槽做法似乎与roxygen其余不一致(2),在不存在@
-delimited标签和插槽也从没有异议去无证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. 我想通过使用
@import
标记,依赖仍然可以正常工作(如果特定插槽需要来自另一个包的非基类)。
So, to summarize, what is the current best-practice for roxygen(2) slots? 总而言之,目前roxygen(2)插槽的最佳实践是什么?
There seem to be three options to consider at the moment: 目前似乎有三种选择:
- A -- Itemized list (as example above).
A - 分项列表(如上例所示)。
- B --
@slot
... but with extra tags/implementation I missed.B -
@slot
...但是有额外的标签/实施我错过了。 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.我无法让@slot在版本中使用roxygen / roxygen2作为上述示例中逐项列表的替代。 Again, the example above does work with roxygen(2).
同样,上面的例子确实适用于roxygen(2)。
- C -- Some alternative tag for specifying slots, like
@param
, that would accomplish the same thing.C - 用于指定插槽的替代标记,如
@param
,可以完成相同的操作。
I'm borrowing/extending this question from a post I made to the roxygen2
development page on github . 我正在从github上的
roxygen2
开发页面发布的帖子中借用/扩展这个问题。
Updated answer for Roxygen2 5.0.1, current as of 6.0.1 更新了Roxygen2 5.0.1的答案,当前版本为6.0.1
For S4, the best practice now is documenting using the @slot
tag: 对于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
On a sidenote, @exportClass
is only necessary in some cases, the general way to export a function is using @export
now. 在旁注中,
@exportClass
仅在某些情况下是必需的,导出函数的一般方法是立即使用@export
。 You also don't have to export a class, unless you want other packages to be able to extend the class. 您也不必导出类,除非您希望其他包能够扩展该类。
See also http://r-pkgs.had.co.nz/namespace.html#exports 另见http://r-pkgs.had.co.nz/namespace.html#exports
Updated answer for Roygen2 3.0.0, current as of 5.0.1. 更新了Roygen2 3.0.0的答案,目前是5.0.1。
For S4, the best practice is documentation in the form: 对于S4,最佳做法是以下形式的文档:
#' \section{Slots}{
#' \describe{
#' \item{\code{a}:}{Object of class \code{"numeric"}.}
#' \item{\code{b}:}{Object of class \code{"character"}.}
#' }
#' }
This is consistent with the internal representation of slots as a list inside the object. 这与作为对象内部列表的槽的内部表示一致。 As you point out, this syntax is different than other lines, and we may hope for a more robust solution in the future that incorporates knowledge of inheritance -- but today that does not exist.
正如您所指出的,这种语法与其他行不同,我们可能希望将来有一个更强大的解决方案,它包含了继承知识 - 但今天却不存在。
As pointed out by @Brian Diggs, this feature was pulled into 3.0.0, further discussion at https://github.com/klutometis/roxygen/pull/85 正如@Brian Diggs指出的那样,这个功能被拉到3.0.0,进一步的讨论在https://github.com/klutometis/roxygen/pull/85
The solution provided by Full Decent is OK if you go for documenting slots in the Rd files itself. 如果您要在Rd文件中记录插槽,那么Full Decent提供的解决方案是可以的。 When using
roxygen2
, you can use the tag @section
to do basically the same with \\describe
. 使用
roxygen2
,您可以使用标签@section
与\\describe
基本相同。 An example: 一个例子:
#' 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
http://r-pkgs.had.co.nz/man.html#man-classes 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. 我还没有尝试过RC,但它现在适用于S4。
It looks like S4 class slots are fully supported under Roxygen2 version 3.0+: 看起来像Roxygen2 3.0+版本完全支持S4类插槽:
http://blog.rstudio.org/2013/12/09/roxygen2-3-0-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." “使用roxygen2记录您的S4类,S4方法和RC类 - 您可以安全地删除使用
@alias
和@usage
变通方法,并且只需依靠roxygen2来做正确的事情。”
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.