312

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で区切られた@タグがなく、スロットが文書化されず、roxygenize(). また、定義されているクラスの継承を文書化する一貫した方法についても何も述べていません。@importタグを使用すると、依存関係は一般的に正常に機能すると思います（特定のスロットが別のパッケージの非基本クラスを必要とする場合） 。

要約すると、roxygen(2) スロットの現在のベストプラクティスは何ですか?

現時点では、次の 3 つのオプションを検討する必要があるようです。

  • A -- 項目別リスト (上記の例のように)。
  • B -- @slot... しかし、余分なタグや実装を見逃していました。上記の例の項目別リストの代わりとして @slot が含まれていたバージョンでは、@slot を roxygen / roxygen2 で動作させることができませんでした。繰り返しますが、上記の例は roxygen(2) で機能します。
  • @paramC --同じことを達成する、スロットを指定するための代替タグ ( など)。

githubroxygen2の開発ページに作成した投稿からこの質問を借用/拡張しています。

4

3 に答える 3

31

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も参照してください。

Roygen2 3.0.0の回答を更新しました。現在、5.0.1の時点です。

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をご覧ください。

于 2012-06-08T21:53:04.203 に答える
20

Rdファイル自体のスロットを文書化する場合は、FullDecentが提供するソリューションで問題ありません。を使用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
于 2013-01-09T13:49:10.937 に答える
16

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 クラスを文書化します。 と を使用@aliasした回避策を安全に削除@usageし、単に roxygen2 に頼って正しいことを行うことができます。」

于 2013-12-10T01:01:08.047 に答える