roxygen2タグまとめ

by
カテゴリ:
タグ:

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

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

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

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

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

まとめ

  • Roxygen2タグ はRStudioの入力補完機能で出現したもの (Roxygen2 v7.1.1)
  • Rdコマンド は Roxygen2タグ に対応するものがあれば記載
  • 主な使い方 は 超訳 + 超要約 が凄いので、メモ程度に思ってもらって Roxygen2タグ や Rdコマンド のリンク先を参考して欲しい。

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

@examplesをcheckしたくない時

@examplesの内容はR CMD check時に実行される。 check時に実行不可な内容があるとエラーになる。これを避ける方法は2つ。できれば1つ目を、それも無理なら2つ目を採用しよう。 checkをパスしたいという理由で乱用しないように注意。

if (interactive()) {}でコードを囲む

対話的なセッションでのみ有効な用例は、if (interactive()) {}でコードを囲む。たとえば、指定のURLをブラウザで開くような操作は、対話的なセッションで行うべきだ。

\dontrun{}でコードを囲む

例えば、存在しないファイルfoo.txtを読み込む例は対話的なセッションであってもErrorになる。そんな時は\dontrun{}でコードを囲む。

#' @examples
#' \dontrun {
#' readLines("foo.txt")
#' }

変更履歴

  • 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にその他の見出しをつけた
    • 目次の追加
      • 変更履歴が細かく目次に載らないよう、見出しをやめ、アイテム化
  • 2020-07-24 20:10
    • typo修正
    • @examplesに関するTipの追加