59

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

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

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

タイトル、説明を使用して新しいS4ジェネリックを完全に文書化し、@param @return @name @aliases @docType @rdname次に対応するだけを使用してS4メソッドを文書化すると@name @aliases @docType @rdname、次の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）？

4

2 に答える 2

47

公式サポート、devtoolsドキュメントで説明されています

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ステートメントは、ジェネリックのステートメントと完全に一致する必要があります。タグは、 WritingRExtensionsの@aliases公式S4ドキュメントセクションで説明されている命名規則に準拠している必要があります。

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

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

完全な例を次に示します。私はこれを構築しましたが、roxygen2のごく最近の開発バージョン（私が利用可能にした）R CMD check testpkgのバグ修正されたフォークを使用して、からのドキュメントレベルの警告なしで動作します。このフォークをシステムにすばやくインストールするには、を使用します。roxygen2の最新バージョンは、見積もりエラー（別の回答で説明）のため、現時点では機能しませんが、これはすぐに組み込まれ、フォークは必要なくなると思います。パッケージの残りの部分のコンテキストでこの例を見て、結果のドキュメント（Rd）ファイルを確認するために、testpkgと呼ばれるgithub上の簡単なテストパッケージとして利用できるようにしました。library("devtools"); install_github("roxygen", "joey711")

##############################################################
#' 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、古いroxygenビネット、およびgithubのroxygen2開発サイトがあります。一般的なRoxygenのRドキュメントに関するSOの質問もあります。

于 2011-09-14T22:20:08.783 に答える
9

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

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

簡単に言えば、

#' @aliases show,helloworld-method

になります

\alias{"show,helloworld-method"}

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

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

于 2011-09-13T06:50:23.733 に答える