对于使用roxygen(2)记录类,指定标题和描述/细节似乎与函数、方法、数据等相同。然而,槽和继承是它们自己的一种动物。在roxygen2中记录S4类的最佳实践(当前的或计划的)是什么?
尽职调查:
我发现在roxygen的早期描述中提到了@slot
标签。
2008年R-forge邮件列表帖子
似乎表明这已经死了,
并且rooxygen中不支持@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)的其余部分不一致,因为没有__abc2分隔的标记,并且槽可以无文档记录而不会受到roxygenize()
的反对。它也没有说明以一致的方式记录所定义类的继承。我认为使用@import
标记的依赖关系通常仍然可以正常工作(如果特定插槽需要来自另一个包的非基类)。
那么,总结一下,目前roxygen(2)插槽的最佳实践是什么?
目前似乎有三种选择可供考虑:
- A——分项列表(如上面的例子)。
- B——
@slot
…但是我错过了额外的标签/实现。我无法让@slot在版本中使用roxygen / roxygen2 它是作为示例中逐项列表的替换而包含的 以上。同样,上述例子也适用于roxygen(2)。李< / >- C——一些用于指定槽的替代标记,如
@param
,将完成相同的事情。
我将这个问题从我在github上的roxygen2
开发页面中引用/扩展。