roxygen2タグまとめ

カテゴリ: r

Roxygen2のタグについての情報が複数箇所に分散していて調べるのが大変なのでまとめた。

超訳 + 超要約 しているので、おかしなところがあれば IssuesTwitter で指摘して頂くか、 PR して欲しい。

Roxygen2を用いると、パッケージ内で定義した関数やデータセット、クラスなどについてのドキュメントや、他パッケージとの依存関係をソースコード内に連続して記述できる。

古くは開発者が適宜作成していたRdファイルがソースコード内のRoxygen2コメントに基いて動的に生成されるため、ユーザーが扱うファイルを限定でき、更に実装とドキュメント化を並行できると良いことづくめだ。

気付きがあれば随時更新していきたい。

まとめ

  • Roxygen2タグ はRStudioの入力補完機能で出現したもの (Roxygen2 v6.1.1)
  • RdコマンドRoxygen2タグ に対応するものがあれば記載
  • 主な使い方 は 超訳 + 超要約 が凄いので、メモ程度に思ってもらって Roxygen2タグRdコマンド のリンク先を参考して欲しい。
Roxygen2タグ Rdコマンド 主な使い方
@aliases \alias ?オブジェクト名 と同じドキュメントに ?指定した文字列 でアクセスできるようにする。
@author \author 著者を 名前, \email{hoge@example.com, \url{example.com}} の形で記述。emailやurlは省略可。
@concepts \concept help.search() 用のキーワード
@describeIn オブジェクトのために新たにRdファイルを作らず、指定したドキュメントを参照する。追加した記述があれば該当ファイルに追記される。
@description \description 概要。タグを用いず、2段落目を @description として扱うことも可能 (後述)。
@details \details 概要。タグを用いず、3段落目を @details として扱うことも可能 (後述)。
@docType \doctype package data methods class についてのドキュメントを作る時に該当するものを指定。 packageの場合、 @name にドキュメント名を指定する。
@evalRd Roxygen2 6.1.0の新機能。パッケージで定義した関数の実行結果を挿入する
@example 用例を記した外部ファイルを指定する
@examples \examples 用例を #’ で始まる次行以降に記す
@export タグの有無でオブジェクトをユーザーが直接扱えるか決める。タグが有ると pkg::name の形でもアクセス可できる。ない場合は pkg:::name としてアクセス。S3やS4のクラスに対するインスタンスの作成可否も決められる。
@exportClass S4クラスの拡張やインスタンスの生成をコントロールするために @export と使い分ける。
@exportMethod S4クラスの拡張やインスタンスの生成をコントロールするために @export と使い分ける。
@family 互いに参照すべきドキュメントに対して family名 を与えておくことで、動的に @seealso を生成する。
@field Reference Classの fields 要素について記述
@format \format データセットの様式 (ベクトル、マトリクス、データフレームなど) を記述。 リストやデータフレームの場合は各要素についても説明した方がいい。
@import 指定したパッケージからexportされているオブジェクトを全て、作成中のパッケージから利用できるようにする。衝突を避けるため使わないが吉。
@importClassesFrom 他パッケージのS4クラスを利用。
@importFrom 指定したパッケージからexportされているオブジェクトを選択的に利用。
@importMethodsFrom 他パッケージのS4クラスのメソッドを利用
@include .Rファイルの名前をスペース区切りで指定すると、該当ファイルを読み込んだ後に、 @include 以降を読む。ファイル冒頭で NULL に対して用いるのが便利。
@inherit @inherit ドキュメント名 で指定したドキュメントから @params @return @references @description @detaills @sections の内容を転載。 @inherit ドキュメント名 return などとして部分的に転載することも可能。
@inheritDotParams ... のドキュメント作成に利用。 @inheritParams と違い関数に該当しない引数でも転載できる。 @inheritDotParams f で関数fの全ての引数を、 a b e:h と続けることで引数 ab に加え e から h までを、 -c と続けることでc 以外の引数を転載できる。
@inheritParams 記載すべき @param の内、未記載の引数をが指定したドキュメントで説明されている場合、転載する。相続権があるのは子まで。孫は不可。
@inheritSection @inheritSection ドキュメント名 セクション名 の形で他のドキュメントのセクションを転載する。
@keywords \keyword RshowDoc(""KEYWORDS"") で一覧できるkeywordを指定。その他のkeywordっぽいものは @concepts で指定する方がいい。
@md Globalにmarkdownが有効化されてない時に、あるチャンク内でのみ有効化したい時に使用
@method \method 基本的に不要。 @mehod generic class の形でS3メソッドディスパッチを表現できるが、指定せずともroxygen2側で解決してくれる。
@name \name 複数のオブジェクトで共有するドキュメントの名前やパッケージ用のドキュメントの名前を指定。前者の場合 NULL に対して作成し、他のオブジェクトから @rdname@describeIn を用いて参照する。
@noMd Globalにmarkdownが有効化されている時に、あるチャンク内でのみ無効化したい時に使用
@noRd タグをつけるとRdファイルが生成されなくなる。exportしない関数 (internal function) 向けに。
@note \note @description に記すほどではない情報。
@param \arguments @param 引数 説明 の形で引数の説明を記述。スペースなしのコンマ区切りで複数の引数に同じ説明を与えられる。
@rawNamespace raw textを NAMESPACE に追加
@rawRd raw textをRdファイルに追加
@rdname オブジェクトのために新たにRdファイルを作らず、指定したドキュメントを参照する。追加した記述があれば該当ファイルに追記される。
@references \reference 参考資料を文字列や \url{} を用いて記述。
@return \value 関数の返り値を記述する。
@section \section 任意のセクションを追加する。書式は @section タイトル: 内容 で、タイトルの後に : が必要。 : タイトルは改行してはならない。
@seealso \seealso 他のドキュメントやウェブサイトへのリンクを貼る。他の関数へは @seealso [function()]
@slot S4クラスの slot の説明を記述。
@source \source S4メソッド作成時に、原典を記載。2番目以降は @reference へ。
@template man-roxygen ディレクトリ中に存在するRoxygenコメントのみからなるRファイルの中身を挿入する。
@templateVar テンプレートファイル中で用い、 @templateVar name value の形で変数を定義。テンプレート利用時には <%= name %> として該当する変数を読み込める。
@title \title オブジェクトのタイトルを記載。オブジェクトのヘルプの冒頭と、パッケージのヘルプを一覧した時に、オブジェクト名の隣に表示される文字列。タグを用いず、1段落目を @title として扱うことも可能 (後述)。
@usage \usage 基本的に不要。オブジェクトの使い方を記述。 @param など必要事項を記載していると @usage がなくても \usage が動的に生成される。
@useDynLib 他のパッケージからコンパイル済みのコードを利用する。

Tips

@title@description@details について

これらの基本的な使い方は

#' @title タイトル
#' @description 概要
#' @details 詳細

といった具合だが、以下のようにタグを用いずに記述する手法もある。

#' タイトルは一段落目に。
#'
#' 概要は二段落目に。タイトルから一行あける。
#'
#' 詳細は三段落目に。概要から一行あける。

@importFrom@seealso について

#' @importFrom pkgA funA
#' @importFrom pkgA funB
#' @importFrom pkgB funA
#' @seealso hoge
#' @seealso fuga

は、以下のように単純化できる。

#' @importFrom pkgA funA funB
#' @importFrom pkgB funA
#' @seealso hoge fuga

更に、改行して見やすくすることもできる。項目が多い時に便利。

#' @importFrom pkgA 
#'   funA 
#'   funB
#' @importFrom pkgB funA
#' @seealso 
#'   hoge
#'   fuga

変更履歴

  • 2018-08-30 12:49
    • @section の使い方を更新
    • 表のレイアウト崩れを修正
  • 2018-08-30 13:46
  • 2018-08-31 09:40
    • Bootstrapを採用し、表を見やすくした
  • 2018-09-07 14:04
    • @seealso で関数のヘルプへのリンクの貼り方を説明。
  • 2018-11-17 10:59
    • Tipsに @importFrom@seealso を簡単に書ける方法を追加
    • @title @description @details についてをTipsに移動
    • 既存のTipsにその他の見出しをつけた
    • 目次の追加
      • 変更履歴が細かく目次に載らないよう、見出しをやめ、アイテム化