内容
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 フィールドに入力する値を指定しておきます。
同じ値の \alias フィールドが 2 つ入力されてしまう (2011/08/22 追記)
なぜか \alias フィールドに 2 つ同じものが出てきてしまうので、原因を調べてみようと思います。
↓
バグっぽいです が、@name を一番下に書けばうまくいくようです。
