web-dev-qa-db-ja.com

roxygen2を使用してS4メソッドを適切に文書化する方法

SOや、これがRoxygen2の将来のバージョンでどのように行われるべきか、または行われる予定であるかについて、他の場所でいくつかの議論を見てきました。しかし、行き詰まっています。S4ジェネリックの文書化についてはどうすればよいですか。 、およびそのメソッド、Roxygen2を使用しますか？まったく新しいジェネリック/メソッドの実用的な例、およびベースS4ジェネリックを拡張するための例は、非常に便利です。個別の（ほとんど）冗長なドキュメントを作成する必要はありません。同じジェネリックのS4メソッドごとに。

デューデリジェンス：「抽出」メソッドの有用な例を追跡しました。しかし、私の質問では時代遅れで不完全なようです。クラスのドキュメントで@slotタグを使用しますが、これはサポートされていません（サポートされなくなりましたか？）。これは、S4ジェネリックのドキュメントを含む完全なRoxygenの例ではなく、コアS4メソッド「[」の拡張のみを示しています。

roxygenを使用してS4 "["および "[<-"メソッドを適切に文書化する方法は？

タイトル、説明@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メソッドの1つの上に含めた、ドキュメントの欠落エラーを生成しなかった完全な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ファイルを見てきましたが、問題が何であるかをすばやく確認するためにそれらについてはさらに詳しく知りません。とにかく、ドキュメントの改訂の直後にRdファイルを操作する必要がないようにroxygen2ソリューションを知りたいと思います。

したがって、これは複数の部分からなる質問です。

  1. Roxygen2を使用したS4ジェネリックとS4メソッドの両方のドキュメントに現在推奨されているアプローチは何ですか？

  2. 完全な詳細を示す良い例がどこかにありますか？

  3. ほとんどのS4メソッドのドキュメントが欠落しているという警告の原因と解決策は何でしょうか（ドキュメントが「欠落している」メソッドは実際にroxygen2によってドキュメントが解析されており、結果のRdファイルは少なくとも十分に機能します）パッケージ内のR CMD build mypkgname）？

rgenericsmethodss4roxygen2
49
Paul McMurdie

Devtoolsdocで説明されている公式サポート

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ジェネリックを文書化するために、ほとんどのジェネリックヘッダーに次の3行が必要であることがわかりました。

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

ここで、_helloworld-methods_は_the_name_of_your_generic-methods_に置き換えられます。これは、ジェネリックとそのすべてのメソッドのドキュメントを保持するRdファイルの名前になります。この命名規則は必須ではありませんが、一般的で便利です。パッケージに名前空間が必要であり、パッケージ内の他のメソッド/関数だけでなく、パッケージのユーザーがこのメソッドを使用できるようにするために、_@export_タグが必要になります。

メソッドを文書化するために、_@rdname_および_@aliases_タグを提供する2行だけが必要であることがわかりました。 _@rdname_ステートメントは、ジェネリックのステートメントと正確に一致する必要があります。 _@aliases_タグは、 R拡張機能の記述 の公式S4ドキュメントセクションで説明されている命名規則に準拠している必要があります。

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

_@aliases_名のコンマの後にスペースを入れないでください。シグニチャリストの最後に_,ANY_をいつ追加するかに関する正確なルールがわかりません。パターンは、すべての_@aliases_シグニチャリストの要素数が、メソッドの中で最も長いシグニチャベクトルの要素数と一致する必要があるようです。以下の例では、メソッドの1つが2要素の署名で定義されているため、他のメソッドのエイリアスタグに_R CMD check_が追加されていない限り、_,ANY_はドキュメントに満足していません。それらの署名定義には1つの要素しかありません。

完全な例を次に示します。私はこれを作成しましたが、 roxygen2のごく最近の開発バージョン（私が利用可能にした） を使用して、_R CMD check testpkg_からのドキュメントレベルの警告なしで動作します。このフォークをシステムにすばやくインストールするには、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ヘッダーに費やされます。ジェネリックには、後で定義されるメソッドのいずれかに現れるすべての特定の引数を含める必要があるため、これにはコードにいくつかの基礎があります。引数リストの_..._の一部として処理される引数は含まれておらず、具体的に文書化する必要はありませんが、_..._自体もジェネリックの上に文書化する必要があることに注意してください（詳細を参照）以下の例）。

ドキュメント化機能の基本の詳細については、 wiki in progress 、 old roxygen vignette 、および githubのroxygen2開発サイト があります。一般に SO Roxygenを使用したRドキュメントに関する質問 もあります。

39
Paul McMurdie

パート（3）の答え（S4メソッドのそれほど見逃されていないドキュメント）は、S4命名規則が使用されているときに\ aliasタグの周りに誤って引用符が追加されているためであることがわかりました。名前の一部としてコンマを含むエイリアスのテキスト処理に起因するバグである可能性があります。これは、この投稿の時点でのroxygen2の最新バージョンにも当てはまります。再現可能な例を使用して、バグのより詳細な説明をroxygen2githubページに投稿しました。

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

簡単に言えば、

#' @aliases show,helloworld-method

になります

\alias{"show,helloworld-method"}

結果のRdファイルで。引用符を削除すると、R CMD check警告が削除され、ドキュメントが作成され、どちらの場合も機能します。

この質問のパート（1）と（2）（ベストプラクティス;良い例）はまだ開いていると思います。

9
Paul McMurdie