如何使用roxygen2正確記錄S4方法




generics methods (2)

我已經在SO和其他地方看到了一些關於在未來版本的Roxygen2中應該如何或將要完成的討論。 但是,我被卡住了。 我應該如何使用Roxygen2記錄S4通用及其方法? 一個全新的通用/方法的工作示例,以及擴展基礎S4泛型的示例將非常有用。 我不想為同一個泛型的每個S4方法製作單獨的(大多數)冗余文檔。

盡職調查:我已經找到了“提取”方法的有用示例。 但是,對於我的問題,它似乎已經過時且不完整。 它在類文檔中使用@slot標記,但不支持(不再?)。 它僅顯示核心S4方法“[”的擴展,而不是包含S4泛型文檔的完整Roxygen示例。

如何正確記錄S4“[”和“[< - ”方法使用roxygen?

如果我用標題,描述@param @return @name @aliases @docType @rdname完全記錄一個新的S4泛型,然後用相應的@name @aliases @docType @rdname記錄S4方法,我得到以下R CMD check警告:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

它首先看起來好像我用這種方式用roxygen2記錄的S4方法都沒有實際起作用。 但是,到目前為止,我已經註意到我的核心方法“show”的擴展沒有相關的錯誤,即使它們的記錄方式與其他方法完全相同。 以下是我在其中一個show方法中包含的完整roxygen文檔的示例,它沒有生成遺漏文檔錯誤:

#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods

因此,我很茫然。 如您所見,我已經包含了R包手冊的S4文檔部分中描述的S4方法的別名約定,即方法應該具有以下名稱的別名(沒有空格):

generic,signature_list-method.

不知何故, R CMD check並未完全理解這一點。

最後,使用以下代碼構建文檔之後:

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

並構建包,我得到了正常運行的文檔。 來自特定方法文檔的任何標題都會在“描述”字段中出現,而不是很尷尬。 所以roxygen2顯然對每個方法的文檔做了一些事情並且在正確的軌道上。 但是,僅僅避免發出大而麻煩的警告是不夠的

> R CMD check mypkgname

我查看了Rd文件,但我對它們的了解更少,以便快速查看問題是什麼,而且無論如何我想知道roxygen2解決方案,這樣我就不必在每次文檔修訂後直接操作Rd文件。

所以這是一個多部分問題:

  1. 對於使用roxygen2的S4通用和S4方法文檔,目前推薦的方法是什麼?

  2. 有沒有一個很好的例子可以顯示完整的細節?

  3. 對於大多數S4方法的文檔缺失的警告可能是原因和解決方案(儘管帶有“缺失”文檔的方法實際上已經通過roxygen2解析了他們的文檔,並且生成的Rd文件至少足以工作在R CMD build mypkgname之後的包中?


官方支持,在devtools doc中解釋

http://r-pkgs.had.co.nz/man.html#man-classes (向下滾動到S4小節)。

該頁面的當前簡短示例將在以下內容中再現(為方便起見):

#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

以上鍊接通過roxygen / devtools非常清楚地解釋了S3,S4和RC支持。 那裡的解釋應該考慮取代下面的舊答案,這個答案現在有用,但不太清楚和復雜。

老答案

這是一個適用於大多數S4方法的示例。

為了記錄S4泛型,我發現大多數通用標題中都需要以下三行:

#' @export
#' @docType methods
#' @rdname helloworld-methods

其中helloworld-methods被替換為the_name_of_your_generic-methods 。 這將是包含泛型及其所有方法的文檔的Rd文件的名稱。 此命名約定不是必需的,但是通用且有用。 @export標記現在是必需的,因為包需要一個命名空間,並且您希望包的用戶可以使用此方法,而不僅僅是包中的其他方法/函數。

對於記錄方法,我發現只需要2行,提供@rdname@aliases標記。 @rdname語句應該與@rdname語句完全匹配。 @aliases標記必須遵守Writing R Extensions的官方S4文檔部分中描述的命名約定。

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method

@aliases名稱中的逗號後面不應有空格。 我不知道何時添加,ANY到簽名列表末尾的確切規則。 模式似乎是所有@aliases簽名列表中的元素數量需要與方法中最長簽名向量中的元素數量相匹配。 在下面的示例中,其中一個方法是使用2元素簽名定義的,因此R CMD check對文檔不滿意,除非,ANY被添加到其他方法的別名標記中,即使它們的簽名定義只有一個要素。

完整的例子如下。 我構建了這個並且沒有來自R CMD check testpkg文檔級警告,使用了最近開發的roxygen2版本(我已經提供)錯誤修復分支 。 要在系統上快速安裝此fork,請使用library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") 。 由於引用錯誤(在單獨的答案中描述),最新版本的roxygen2目前無法正常工作,但我希望很快就會合併,而且我的分叉也不是必需的。 為了在包的其餘部分的上下文中查看此示例,並查看生成的文檔(Rd)文件,我已將其作為一個名為testpkg github上的普通測試包提供。

##############################################################
#' The title, in this case: Helloworld-ify the argument.
#'
#' Some additional details about this S4 generic and its methods.
#' The extra blank line between this section and the title is
#' critical for roxygen2 to differentiate the title from the
#' description section.
#'
#' @param x Description of \code{x}. The main argument in this
#'  example. Most often has such and such properties.
#'
#' @param y Description of \code{y}. An argument that is rarely
#'  used by \code{"helloworld"} methods. 
#'
#' @param ... Additional argument list that might not ever
#'  be used.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#' 
#' @seealso \code{\link{print}} and \code{\link{cat}}
#' 
#' @export
#' @docType methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
#' helloworld(char2helloworld("thisismystring"))
#' helloworld(matrix(0,3,3))
#' helloworld(list(0,0,0))
#' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
    cat("Hello World!")
    cat("\n")
    standardGeneric("helloworld")
})

#' @rdname helloworld-methods
#' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
    cat(class(x))
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
    show(x)
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
    show(x)
})

此示例假定您不需要單獨的特定於方法的文檔,因為您的方法沒有從基於通用文檔的預期行為中產生過多的偏差。 roxygen2中有一些方法可以使用@usage標記來處理這種替代案例,但是通過單獨的SO問題可以更好地處理細節。

因此,您的大部分文檔工作都會進入通用定義之上的roxygen標頭。 這在代碼中有一些基礎,因為泛型應包括出現在任何後續定義的方法中的所有特定參數。 請注意,參數列表中作為...的一部分處理的參數不包含在內,不應具體記錄,但...本身也應記錄在泛型之上(參見下面的完整示例)。

有關記錄功能的基礎知識的更多詳細信息,有一個正在進行維基舊的roxygen vignette ,以及github上roxygen2開發站點 。 關於R一般的Rxygen文檔也有一個問題 。


我已經找到了第(3)部分的答案 - S4方法的不那麼缺失的文檔 - 是因為當使用S4命名約定時,在\ alias標記周圍錯誤地添加了引號; 很可能是由於別名的文本處理導致的錯誤,該別名包含逗號作為其名稱的一部分。 這篇文章發佈時,最新版本的roxygen2仍然如此。 我剛剛在roxygen2 github頁面上發布了一個關於bug的更全面的描述:

https://github.com/klutometis/roxygen/issues/40

簡單地說,

#' @aliases show,helloworld-method

\alias{"show,helloworld-method"}

在生成的Rd文件中。 刪除引號將刪除R CMD check警告,並且文檔構建並在兩種情況下都起作用。

我認為這個問題的部分(1)和(2)(最佳實踐;很好的例子)仍然是開放的。





roxygen2