class - 如何使用Roxygen2正確記錄S4類插槽?




slot (2)

roxygen2 v4.1 +和哈德利最新的文檔為此:

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

我還沒有嘗試過,但現在適用於S4。

先前

它看起來像Roxygen2 3.0+版本完全支持S4類插槽:

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

“使用roxygen2記錄您的S4課程,S4課程和RC課程 - 您可以安全地移除使用@alias@usage解決方法,並且只需依賴roxygen2即可做正確的事情。”

為了記錄具有roxygen(2)的類,指定標題和描述/細節似乎與函數,方法,數據等相同。但是,插槽和繼承是它們自己的動物。 目前或計劃的最佳做法是如何記錄roxygen2中的S4課程?

盡職調查:

我在早期的roxygen描述中發現了一個@slot標籤。 2008 R-forge郵件列表帖子似乎表明這已經死了,並且在@slot中沒有對@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)不一致,因為沒有@ -delimited標記,並且槽可能沒有記錄而沒有來自roxygenize()反對。 它也沒有提到一個一致的方法來記錄正在定義的類的繼承。 我想依賴依然一般工作正常(如果一個特定的插槽需要從另一個包的非基類)使用@import標記。

因此,總結一下,roxygen(2)插槽目前的最佳做法是什麼?

目前似乎有三種選擇需要考慮:

  • A - 分項清單(如上所示)。
  • B - @slot ...但有額外的標籤/執行我錯過了。 我無法使用@slot與roxygen / roxygen2一起使用,在上面的示例中,它包含了作為條目列表的替代品的版本。 再次,上面的例子與roxygen(2)一起工作。
  • C - 用於指定插槽的一些替代標籤,如@param ,可以實現同樣的功能。

我借用/擴展了這個問題,從我發佈到github上的roxygen2開發頁面。


Roxygen2 5.0.1的更新回答,目前為6.0.1

對於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,在github.com/klutometis/roxygen/pull/85進一步討論





roxygen2