web-dev-qa-db-ja.com

Roxygen2を使用してS4クラススロットを適切にドキュメント化する方法は？

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

適当な注意：

Roxygenの初期の説明で@slotタグの言及を見つけました。 2008 R-forgeメーリングリストの投稿 これは死んでいることを示しているようで、roxygenでは@slotのサポートはありません：

これはroxygen2にも当てはまりますか？前述の投稿では、ユーザーが代わりにLaTeXマークアップを使用して独自の項目リストを作成する必要があることを示唆しています。例えば。 "character"クラスを拡張する新しいS4クラスは、次のようにコーディングおよび文書化されます。

#' 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のスロットをドキュメント化する方法は、@で区切られたタグがなく、スロットはroxygenize()から異議なしにドキュメント化されないため、残りのroxygen（2）と矛盾しているようです。また、定義されているクラスの継承を文書化する一貫した方法については何も述べていません。 @importタグを使用すると、依存関係は一般に（特定のスロットが別のパッケージの非ベースクラスを必要とする場合）通常は正常に機能すると思います。

したがって、要約すると、roxygen（2）スロットの現在のベストプラクティスは何ですか？

現時点で考慮すべき3つのオプションがあるようです。

  • A-項目別リスト（上記の例）。
  • B-@slot ...が、追加のタグ/実装では見逃しました。 @slotをroxygen/roxygen2で動作させることができませんでした。これは、上記の例の項目リストの代替として含まれていました。繰り返しますが、上記の例はroxygen（2）で動作します。
  • C-同じことを達成する@paramなどのスロットを指定するための代替タグ。

github のroxygen2開発ページに行った投稿からこの質問を借りています。

classrs4slotroxygen2
301
Paul McMurdie

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

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

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

以前

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

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

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

14
Paul McMurdie

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.0.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 で議論されました。

28
William Entriken

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
18
Joris Meys