1. ホーム
  2. クラス

[解決済み】Roxygen2を使ってS4クラススロットを適切にドキュメント化する方法は?

2022-03-28 05:51:47

質問

roxygen(2)でクラスを文書化する場合、タイトルと説明/詳細を指定することは、関数、メソッド、データなどの場合と同じように見えます。しかし、スロットと継承はそれとは別の種類のものです。roxygen2でS4クラスのドキュメントを作成するためのベストプラクティスは何でしょうか(現在、あるいは計画中)?

デューディリジェンス

の記載を発見しました。 @slot タグが使われています。 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) の他の部分と矛盾しているように思われます。 @ -からの異論がなく、スロットはドキュメント化されない可能性があります。 roxygenize() . また、定義されているクラスの継承を文書化する一貫した方法については、何も書かれていません。私は、(特定のスロットが他のパッケージの非基本クラスを必要とする場合) 依存関係がまだ一般的にうまく機能していると想像しています。 @import タグを使用します。

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

今のところ、3つの選択肢が考えられるようです。

  • A -- 項目別リスト(上記の例と同じ)。
  • B -- @slot ...ただし、私が見落としたタグや実装を追加しています。roxygen / roxygen2 で @slot を動作させることができませんでした。 この例では、項目別リストの代わりとして含まれています。 上記の 繰り返しますが、上の例はroxygen(2)で動作します。
  • C -- スロットを指定するための何らかの代替タグ、例えば @param というのは、同じことを達成するためです。

に投稿した質問を借用/拡張しています。 roxygen2 の開発ページです。 ギズブ .

解決方法は?

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/

S4クラス、S4メソッド、RCクラスをroxygen2で文書化することで、以下のような回避策を安全に取り除くことができます。 @alias@usage そして、roxygen2が正しいことをするよう、ただただ頼るのみです。