どのように適切に文書S4方法を用いroxygen2

https://stackoverflow.com/questions/7356120

28-10-2019
|

質問

いくつかの議論などについてこれまでの将来のバージョンRoxygen2.しかし、と言っても過言ではない.いつ、どのように行を記録し、S4、その方法を用いRoxygen2?作例のためのブランドの新しい汎用方法は、例として拡張ベースS4一般れまでのものと便利です。したいと思わないを作り分けて(中心)冗長各メソッドのドキュメントを参照S4方法と同等のクラスを提供します。.

によりdilligence:していま識を有例の抽出方法である。しかし、まさに時代遅れで不完全のための私の質問です。使用す@スロットタグのクラスによる記録になっていましたが?) サポート。そして、コアS4法"["というより完全Roxygen例を含む文書のS4のクラスを提供します。.

どのように適切に文書S4"["および"[<-"の方法を用いroxygen?

だ完全に文書を新規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.

とりあえず最初のものとなっS4メソッドはこのクリエイティブ-ライブラリー roxygen2たが実際に動いています。しかし、これまでのところ、って僕の拡張機能の中核法"表示"にしていない関連するエラーも記録と正確に同じになります。この例では、完全にroxygen書類はそれぞれ上記に示す方法になかったの欠損文書のエラー:

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

このようんです。ご覧の通り、私の条約の別名S4示のS4文書のRパッケージマニュアル, とその方法はエイリアスの名前(な空間):

generic,signature_list-method.

なんとかこなっているか R CMD check.

最後に、後の建物の利用:

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

建このパッケージには、取得し機能します。他のタイトルから特定のメソッドのドキュメント風の'Description'の分野ではなく祭.でroxygen2明らかにしたものを各メソッドのドキュメントの右します。しかし、これでは不十分でな大きなや患者からの警告

> R CMD check mypkgname

私の場合の近似式は以下のようになRdファイルがいもについて迅速に対応していません。問題は、とにかくお知りになりたいroxygen2に行うことができ、かつ、そのままに操るRdファイルを直接の後、各文書の改訂される。

そこでマルチパートの質問:

何が現在のおすすめアプローチの両方S4アファーマティブ-アクS4方法書類とroxygen2?
あとえば可能かを示す完全ないんですよ。
どのようにな原因は、ソリューションの警告文書のほとんどのS4方法が欠けていなくても、法"missing"ドキュメンテーションを実際にしていたdocフレーバを構文解析による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 Genericsを文書化するために、私の一般的なヘッダーのほとんどで次の3行が必要であることがわかります。

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

どこ helloworld-methods 置き換えられます the_name_of_your_generic-methods. 。これは、汎用およびそのすべてのメソッドのドキュメントを保持するRDファイルの名前になります。この命名規則は必須ではありませんが、一般的で有用です。 @export パッケージには名前空間が必要であり、パッケージの他の方法/機能だけでなく、パッケージのユーザーがこの方法を利用できるようにするために、タグが必要です。

方法を文書化するために、私は2行しか必要であり、 @rdname と @aliases 鬼ごっこ。 @rdname ステートメントは、一般的なものと正確に一致する必要があります。 @aliases タグは、公式のS4ドキュメントセクションに記載されている命名規則に付着する必要があります R拡張機能を書きます.

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

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

完全な例が続きます。私はこれを作成しましたが、それはドキュメントレベルの警告なしで動作します R CMD check testpkg, 、を使って Roxygen2のごく最近の開発バージョンのバグ固定フォーク（私が利用できるようにしました）. 。システムにこのフォークをすばやくインストールするには、使用してください library("devtools"); install_github("roxygen", "joey711"). 。 Roxygen2の最新のバージョンは、引用エラー（別の回答で説明されている）のためにこの瞬間は機能しませんが、これはすぐに組み込まれ、フォークは必要ないと思います。パッケージの残りの部分のコンテキストでこの例を見て、結果のドキュメント（RD）ファイルを見るために、GitHubの些細なテストパッケージとして呼び出して利用できるようにしました testpkg.

##############################################################
#' 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 タグですが、詳細は別の質問によってより適切に処理されます。

したがって、ドキュメントの努力のほとんどは、一般的な定義の上にRoxygenヘッダーに入ります。これにはコードに何らかの根拠があります。なぜなら、一般的なものには、後に定義されたメソッドのいずれかに表示されるすべての特定の引数を含める必要があるからです。の一部として処理される引数に注意してください ... 引数リストには含まれておらず、具体的に文書化されるべきではありませんが、 ... それ自体もジェネリックの上に文書化する必要があります（以下の完全な例を参照）。

文書化関数の基本の詳細については、進行中のウィキ, 、古いroxygenビネット, 、と同様に GithubのRoxygen2開発サイト. 。 aもありますしたがって、Roxygenを使用したRドキュメントに関する質問一般に。

他のヒント

って追跡され、その答え部(3)のない文書のS4析--クラスでの二重引用符で追加される誤周辺のエイリアスのタグがS4命名規則を使用しそのバグによるテキストの取り扱いのエイリアスを含むコンマで区切っての名前です。このままだと、最新バージョンのroxygen2時のこと。かして徹底解説のバグを再現可能例にroxygen2githubのページ:

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

簡単に言うと、

#' @aliases show,helloworld-method

となり

\alias{"show,helloworld-method"}

によRdファイルです。削除の見積もりを取り除く R CMD check 警告、およびドキュメンテーションを構築、機能性もある。

と思いパーツ(1)と(2)この問題の最良慣行良い例がスタンドオープン。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow