roxygen(2)を使用してクラスをドキュメント化する場合、タイトルと説明/詳細の指定は、関数、メソッド、データなどの場合と同じように見えます。ただし、スロットと継承は独自の動物です。roxygen2でS4クラスを文書化するための現在または計画中のベストプラクティスは何ですか?
適当な注意:
@slot
roxygenの初期の説明でタグの言及を見つけました。
2008年のR-forgeメーリングリストの投稿
は、これが@slot
無効であり、roxygenでのサポートがないことを示しているようです。
これはroxygen2に当てはまりますか?前述の投稿では、ユーザーは代わりにLaTeXマークアップを使用して独自の項目別リストを作成することを推奨しています。たとえば、クラスを拡張する新しいS4クラスは、次の"character"
ようにコーディングおよびドキュメント化されます。
#' 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)スロットの現在のベストプラクティスは何ですか?
現時点で考慮すべき3つのオプションがあるようです。
- A-(上記の例のように)項目別リスト。
- B
@slot
-...しかし、余分なタグ/実装があるので見逃しました。上記の例の項目別リストの代わりとして含まれているバージョンでは、@ slotをroxygen / roxygen2で動作させることができませんでした。繰り返しますが、上記の例はroxygen(2)でも機能します。- C-スロットを指定するためのいくつかの代替タグ
@param
。たとえば、同じことを実行します。
私はgithubのroxygen2
開発ページへの投稿からこの質問を借用/拡張しています。
setClass
ステートメントがに比べてはるかに少ないのは嬉しいですsetMethod
。一度@slot
実装された変更は、それほど苦痛ではありません。
@slot
おそらく長期的に望むものですが、最初に実装する必要があります...