Triad sou.

Reference class に roxygen 用のコメントを入れる方法

R

お詫び

下記の内容は不十分だったため、roxygen2 について記事を書きました。

内容

Reference class を用いたパッケージの R スクリプトに roxygen 用のコメントを入れる方法を模索してみました。
S4 の様なドキュメントの自動生成は難しそうですが、充分使えそうな形にはまとまったので、メモしておきます。

roxygen コメントの基本

roxygen コメントをパッケージ用の関数やクラスの定義の前に書いておくと、roxygenize() 関数で Rd ファイルを自動的に作ってくれます。
Rd ファイルを手動でいちいち編集するのは手間がかかるため、とても便利なパッケージだと思います。

とっても簡単な例

f1 というとても簡単な関数に roxygen コメントをつけてみました。

#' Description
#'
#' Details
#'
#' @title f1: A test function
#' @param x numeric number
f1 <- function(x) {
  print(x)
}

roxygen コメントは [#'] で始まります。
一行目には \description フィールドに入力したい内容を書き込みます、一行に収まるようにする必要があります。
二行目以降には \details フィールドに入力したい内容を書き込みます、複数行に分かれていても問題ありません。
それ以外のフィールドは、\details フィールドの後に [#' @keyword] の形式で入力しておきます。
そして、最後に続けて関数定義を入力します。
上の例では区切りに空の行を入力していますが、必須ではありません。


上のコメントを入れたものに roxygenize() 関数を適用して生成される f1.Rd ファイルは

\name{f1}
\alias{f1}
\title{f1: A test function}
\usage{f1(x)
}
\description{Description}
\details{Details}
\arguments{\item{x}{numeric number}
}

のようになります。
シンプルな関数の場合は、\name, \alias, \usage フィールドを自動的に作成してくれます。


ヘルプファイルは



こんな感じになります。

Reference class 用サンプルパッケージ

上記のように、パッケージ作成に通常の関数などを利用している場合はとても簡単で、ソース管理の手間が省けるのですが、残念ながら Reference class にはまだ対応していません。
Re: Status of R5 support (Roxygen-devel mailing list) の様に書いても単なるコメントとして判定されるため、S4 class の様にメソッド用の roxygen コメントを別に書かなければなりません。
ということで、Reference class 用サンプルパッケージを作っていきます。

パッケージの Rd ファイル用の roxygen コメント

パッケージの Rd ファイルも以下の様に書いておくことができます。

#' Description: A Test Package for Reference Class Documents Using 'roxygen'
#'
#' Details: This package is an example of how to document reference class methods.
#'
#' @rdname testRefclassPkg-package
#' @docType package
#' @aliases testRefclassPkg-package
#' @keywords documentation
#'
#' @title testRefclassPkg: A test package for reference class documents using 'roxygen'
#' @author Triad sou. \email{triadsou@@gmail.com}
#' @seealso \code{\link[methods:ReferenceClasses]{ReferenceClasses}}
#' @exportPattern '^[^\\.]'
#'
#' @name testRefclassPkg
NULL

ポイント

  • @rdname testRefclassPkg-package: Rd ファイル名を指定します、好きな名前を指定して問題ありません。
  • @docType package: パッケージ用の Rd ファイルであることを指定します。
  • @exportPattern '^[^\\.]': NAMESPACE ファイルを自動生成するために、すべてにマッチする directive を書いておきます。
  • @name testRefclassPkg: \name フィールドを指定します。パッケージの roxygen コメントを書く場合、最後に続けて関数定義やクラス定義などを記入できないため、NULL や {} などを記入します。この場合、関数名やクラス名が存在しないため、\name フィールドを自動的に作成できずエラーが発生してしまいますが、自分で指定しておけば問題ありません。alias が勝手に複製されるバグを回避するため、一番最後に書いてください。

Reference class の定義と Rd ファイル用の roxygen コメント

基本的に S4 class と変わらないです。

#' Description: My Test Class
#'
#' Details: \code{test_refclass} class is a test reference class that has three methods.
#'
#' @docType class
#' @aliases test_refclass-class
#'
#' @title test_refclass: My test class
#' @slot f1 numeric number of a test field
#' @slot f2 numeric number of a test field
#' @keywords documentation
#' @seealso \code{\link{m1}}, \code{\link{m2}}, \code{\link{m3}}
#'
#' @name test_refclass
test_refclass <- setRefClass(

  Class = "test_refclass",
  
  fields = c("f1", "f2"),

  methods = list(

    m1 = function(arg1 = 1) {
      f1 <<- arg1
    },

    m2 = function(arg1) {
      if (class(f1) == "uninitializedField") f1 <<- 2
      f1 + arg1 * 2
    },

    m3 = function(arg1) {
      if (class(f1) == "uninitializedField") f1 <<- 3
      f1 + arg1 * 3
    }

  )
)

ポイント

  • @docType class: クラス用の Rd ファイルであることを指定します。
  • @slot: fields は @slot で記入していきます。複数のフィールドがある場合は @slot を複数書いていけば OK です。roxygen は @slot や @section でエラーは出ないものの、何も処理をしてはいないので、適切にドキュメントを作成できません。roxygen2 を利用した方が良いでしょう。
  • @aliases test_refclass-class: クラス用の Rd ファイルでは、\alias フィールドに [クラス名-method] が指定されていなければならないので指定しておきます。
  • @name test_refclass: 自動判定の場合も、alias が勝手に複製されるバグがあるので、一番最後に書いてください。

メソッドの Rd ファイル用の roxygen コメント

メソッドの Rd ファイル用の roxygen コメントは以下の様に書いておけばよいでしょう。

#' Description: \code{m1} method
#'
#' Details: \code{m1} method set a value to \code{f1}.
#'
#' @rdname test_refclass-m1
#' @docType methods
#' @aliases m1,test_refclass-method
#'
#' @title m1,test_refclass-method: The m1 method of test_refclass class
#' @param arg1 numeric number of a test argument
#' @usage \S4method{m1}{test_refclass}(arg1)
#' @examples
#' classObj <- test_refclass$new()
#' print(classObj$m1(10))
#' @seealso \code{\link{test_refclass}}
#'
#' @name m1
NULL

#' Description: \code{m2} method
#'
#' Details: \code{m1} method return \code{f1 + arg1 * 2}.
#'
#' @rdname test_refclass-m2
#' @docType methods
#' @aliases m2,test_refclass-method
#' 
#' @title m2,test_refclass-method: The m2 method of test_refclass class
#' @param arg1 numeric number of a test argument
#' @usage \S4method{m2}{test_refclass}(arg1)
#' @examples
#' classObj <- test_refclass$new()
#' print(classObj$m2(10))
#' @seealso \code{\link{test_refclass}}
#'
#' @name m2
NULL

#' Description: \code{m3} method
#'
#' Details: \code{m3} method return \code{f1 + arg1 * 3}.
#'
#' @rdname test_refclass-m3
#' @docType methods
#' @aliases m3,test_refclass-method
#'
#' @title m3,test_refclass-method: The m3 method of test_refclass class
#' @param arg1 numeric number of a test argument
#' @usage \S4method{m3}{test_refclass}(arg1)
#' @examples
#' classObj <- test_refclass$new()
#' print(classObj$m3(10))
#' @seealso \code{\link{test_refclass}}
#'
#' @name m3
NULL

ポイント

  • @docType methods: メソッド用の Rd ファイルであることを指定します。
  • @usage: 面倒なので \S4method{generic}{signature_list}(argument_list) を流用します。
  • @name: パッケージの Rd ファイルの場合と同様の理由で、\name フィールドに入力する値を指定しておきます。
表示例

上記のスクリプトを *.R ファイルとして保存し、DESCRIPTION ファイルなど他の必要なファイルと一緒に適切にディレクトリに配置し、

require(roxygen)
roxygenize(path, "testRefclassPkg", copy.package = FALSE, use.Rd2 = TRUE)

の様に roxygenize() 関数を適用すると、Rd ファイルが生成されますので、これらをまとめてパッケージ化すると完成です。


以下に、パッケージ化してインストール後に生成されたドキュメントを示しておきます (表示には helpr を利用)。





同じ値の \alias フィールドが 2 つ入力されてしまう (2011/08/22 追記)

なぜか \alias フィールドに 2 つ同じものが出てきてしまうので、原因を調べてみようと思います。


↓


バグっぽいです が、@name を一番下に書けばうまくいくようです。