Roxygen2を使用してS4クラススロットを適切に文書化する方法?


306

roxygen(2)を使用してクラスをドキュメント化する場合、タイトルと説明/詳細の指定は、関数、メソッド、データなどの場合と同じように見えます。ただし、スロットと継承は独自の動物です。roxygen2でS4クラスを文書化するための現在または計画中のベストプラクティスは何ですか?

適当な注意:

@slotroxygenの初期の説明でタグの言及を見つけました。 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開発ページへの投稿からこの質問を借用/拡張しています。


16
@slotおそらく長期的に望むものですが、最初に実装する必要があります...
hadley

3
ありがとう!知っておくと便利です。コードのsetClassステートメントがに比べてはるかに少ないのは嬉しいですsetMethod。一度@slot実装された変更は、それほど苦痛ではありません。
ポールマクマーディ2011

8
@スロットに関するディスカッション:github.com/klutometis/roxygen/pull/85
Brian Diggs


2
S4クラスはRoxygen2バージョン3(githubで入手可能)で完全にサポートされるようになりました。
グレゴールトーマス

回答:


29

Roxygen2 5.0.1の最新の回答、6.0.1現在

S4の場合のベストプラクティスは、@slotタグを使用して文書化することです。

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export

補足として@exportClass、いくつかの場合にのみ必要ですが、関数をエクスポートする一般的な方法は@export現在使用しています。他のパッケージでクラスを拡張できるようにする必要がない限り、クラスをエクスポートする必要もありません。

http://r-pkgs.had.co.nz/namespace.html#exportsも参照してください

5.1の時点で最新のRoygen2 3.0.0の回答を更新しました。

S4の場合、ベストプラクティスは次の形式のドキュメントです。

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

これは、オブジェクト内のリストとしてのスロットの内部表現と一致しています。ご指摘のとおり、この構文は他の行とは異なり、継承の知識を組み込んだより堅牢なソリューションが将来的に望まれるかもしれませんが、今日は存在しません。

@Brian Diggsが指摘したように、この機能は3.0.0に組み込まれました。詳細については、https://github.com/klutometis/roxygen/pull/85をご覧ください。


2
@Brian Diggsによる実装を使用しましたか?うまくいきますか?そのアプローチについていくつかの詳細を提供できると思いますか(したがって、@slotソリューションに似たもの)。私はそれを試すことに慣れておらず、この保留中の@slotソリューションを(おそらく怠惰に)待っています。私はそれが問題の提起方法ではないことを知っていますが、コメント(@hadleyのものを含む)に基づいて@slot、「本当の」答えであるようです。私の質問にあるような項目別リストが現在のベストプラクティスであるという評価に同意しますが、うまくいけばすぐに置き換えられるでしょう。
ポールマクマーディ

19

Rdファイル自体にスロットを文書化する場合、Full Decentが提供するソリューションは問題ありません。使用している場合roxygen2、あなたはタグを使用することができます@sectionと基本的に同じことをやって\describe。例:

#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots: 
#'  \describe{
#'    \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#'    \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#'  }
#'
#' @note You can still add notes
#' @name EXAMPLE 
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys

14

roxygen2 v4.1 +およびこれを行うためのHadleyの最新のドキュメント:

http://r-pkgs.had.co.nz/man.html#man-classes

RCではまだ試していませんが、S4で動作します。

以前は

S4クラススロットはRoxygen2バージョン3.0以降で完全にサポートされているようです:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

「roxygen2を使用してS4クラス、S4メソッド、RCクラスを文書化します。and @aliasとを使用した回避策を安全に削除でき@usage、roxygen2に依存して正しいことを実行できます。」


2
@slotは完全に機能します。これを使用して(または@field)、S3クラスを偽造することもできます。
Brandon Bertelsen
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.