roxygen2タグまとめ

カテゴリ: r

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

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

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

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

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

まとめ

  • Roxygen2タグ はRStudioの入力補完機能で出現したもの (Roxygen2 v6.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

変更履歴

  • 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にその他の見出しをつけた
    • 目次の追加
      • 変更履歴が細かく目次に載らないよう、見出しをやめ、アイテム化