Roxygenドキュメントの記述

Rパッケージの関数、データセット、クラスの完全なroxygen2ドキュメントを作成する。

使用タイミング

• 新規エクスポート関数にドキュメントを追加する時
• 内部ヘルパー関数をドキュメント化する時
• パッケージのデータセットをドキュメント化する時
• S3/S4/R6クラスとメソッドをドキュメント化する時
• ドキュメント関連の

  R CMD check

  ノートを修正する時

入力

• 必須: ドキュメント化するR関数、データセット、またはクラス
• 任意: 相互参照のための関連関数（

  @family

  、

  @seealso

  ）
• 任意: 関数をエクスポートすべきかどうか

手順

ステップ1: 関数ドキュメントの記述

roxygenコメントを関数の直上に配置する：

#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
  # implementation
}

期待結果： タイトル、説明文、各パラメータの

@param

@return

@examples

@export

失敗時： タグについて不明な場合は

?roxygen2::rd_roclet

@return

ステップ2: 必須タグリファレンス

#' Title

#' Description

@param

@return

@examples

@export

@family

@seealso

@keywords internal

期待結果： 関数タイプに必要なすべての必須タグが特定される。エクスポートされる関数は最低限

@param

@return

@examples

@export

失敗時： タグについて不明な場合はroxygen2ドキュメントで使用法と構文を確認する。

ステップ3: データセットのドキュメント化

R/data.R

#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#'   \item{date}{Date of observation}
#'   \item{city}{City name}
#'   \item{temp_c}{Temperature in Celsius}
#'   \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"

期待結果：

R/data.R

@format

@source

失敗時：

R CMD check

"city_temperatures"

usethis::use_data()

ステップ4: パッケージのドキュメント化

R/packagename-package.R

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

期待結果：

R/packagename-package.R

@keywords internal

"_PACKAGE"

devtools::document()

man/packagename-package.Rd

失敗時：

R CMD check

R/<packagename>-package.R

"_PACKAGE"

ステップ5: 特殊ケースの処理

名前にドットが含まれる関数（S3メソッド）：

#' @export
#' @rdname process
process.myclass <- function(x, ...) {
  # S3 method
}

@inheritParams

#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
  # implementation
}

.data

#' @importFrom rlang .data
my_function <- function(df) {
  dplyr::filter(df, .data$column > 5)
}

期待結果： 特殊ケース（S3メソッド、継承パラメータ、

.data

@rdname

@inheritParams

失敗時：

R CMD check

#' @importFrom rlang .data

utils::globalVariables()

ステップ6: ドキュメントの生成

devtools::document()

期待結果：

man/

.Rd

NAMESPACE

失敗時： roxygenの構文エラーを確認する。一般的な問題：

\describe{}

#'

devtools::document()

バリデーション

• エクスポートされるすべての関数が

  @param

  、

  @return

  、

  @examples

  を持つ

• devtools::document()

  がエラーなく実行される

• devtools::check()

  がドキュメント警告を示さない

• @family

  タグが関連関数を正しくグループ化している
• 例がエラーなく実行される（

  devtools::run_examples()

  でテスト）

よくある落とし穴

• @return

  の欠如: CRANはエクスポートされるすべての関数に戻り値のドキュメントを要求する
• インターネット/認証が必要な例:

  \dontrun{}

  で囲み、理由を説明するコメントを追加する
• 実行が遅い例: CRANには長すぎるが動作する例には

  \donttest{}

  を使用する
• roxygenでのMarkdown: DESCRIPTIONで

  Roxygen: list(markdown = TRUE)

  を有効化する

• devtools::document()

  の実行忘れ: manページは生成されるものであり、手動で記述するものではない

関連スキル

• create-r-package

  - rox ygen設定を含む初期パッケージセットアップ

• write-testthat-tests

  - ドキュメント化した関数のテスト

• write-vignette

  - 関数リファレンスを超えた長文ドキュメント

• submit-to-cran

  - CRANのドキュメント要件