0Pricing
R Academy · レッスン

roxygen2 による関数ドキュメントの作成

@param、@return、@examples、@export タグを記述し、ドキュメントを自動生成します。

「roxygen2 による関数ドキュメントの作成」はCoddyKit上の無料R Academyレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはR Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 R Academyコースには全4レッスンが含まれています。

roxygen2とは

roxygen2を使うと、関数の直前に#'で始まる特別な形式のコメントとして、Rのドキュメントを直接記述できます。devtools::document()を実行すると、roxygen2がこれらのコメントを解析し、man/*.Rdファイルを生成するとともに、NAMESPACEを自動的に更新します。

roxygen2の最小ブロック

最も簡単なドキュメントブロックには、少なくともタイトルと説明が必要です。最初の文（最初のピリオドまたは空行まで）がタイトルになります。続く段落が説明になります。

# R/add.R
#
# #' Add two numbers
# #'
# #' Computes the sum of x and y. Both arguments must be numeric.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@titleと@descriptionタグ

最初の段落を利用する規則だけでは不十分な場合は、@titleと@descriptionタグを明示的に使用します。たとえば、タイトルを関数名と異なるものにする必要がある場合や、説明が複数の段落にわたる場合です。

# #' @title Safe Addition of Numeric Values
# #' @description
# #' Adds two numeric vectors element-wise.
# #' Returns NA where either input is NA.
# #' Useful for financial calculations where NA propagation matters.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@param — 引数をドキュメント化する

#' @param name Descriptionは、1つの関数引数をドキュメント化します。引数ごとに@param行を1行ずつ記述します。説明には、期待される型と、その引数が制御する内容を記載してください。

# #' Add two numbers
# #'
# #' @param x A numeric vector. The first operand.
# #' @param y A numeric vector. The second operand. Must be the same length as x
# #'   or length 1 (recycled).
# #'
# #' @export
# add <- function(x, y) {
#   if (!is.numeric(x) || !is.numeric(y)) stop('x and y must be numeric')
#   x + y
# }

@return — 戻り値をドキュメント化する

#' @return Descriptionは、関数が返す値を説明します。戻り値の型、クラス、構造を記載してください。これはCRANへの提出に必須です。

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of the same length as the longer of x or y,
# #'   containing the element-wise sums.
# #'
# #' @export
# add <- function(x, y) x + y

@examples — 実行可能なコード例

#' @examplesは、ヘルプページに表示され、R CMD checkによって実行されるコードを提供します。例は5秒未満で完了し、外部リソース（ネットワークやファイル）を必要としないようにします。各行は通常のRコードであり、特別な接頭辞は必要ありません。

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of element-wise sums.
# #' @examples
# #' add(1, 2)
# #' add(c(1, 2, 3), c(10, 20, 30))
# #' add(0, -5)
# #' @export
# add <- function(x, y) x + y

@export — 関数を公開する

#' @exportは、関数をNAMESPACEに追加するようroxygen2に指示し、パッケージのユーザーが利用できるようにします。@exportのない関数は内部関数です。パッケージ内からは呼び出せますが、ユーザーは（:::を使わない限り）呼び出せません。

# Public function — exported:
# #' @export
# add <- function(x, y) x + y
#
# Internal helper — not exported:
# check_numeric <- function(x) {
#   if (!is.numeric(x)) stop('Expected numeric')
# }
#
# After devtools::document(), NAMESPACE will contain:
# export(add)
# but NOT check_numeric

@importFrom — 関数をインポートする

#' @importFrom pkg fn1 fn2は、パッケージから特定の関数を名前空間にインポートします。これにより、pkg::接頭辞なしで呼び出せます。ただし、使用は控えめにしてください。明示的なpkg::fn()のほうがわかりやすく、名前空間の汚染も避けられます。

# Option 1 — @importFrom (adds to NAMESPACE, no pkg:: needed):
# #' @importFrom stringr str_trim str_to_lower
# clean <- function(x) str_to_lower(str_trim(x))
#
# Option 2 — explicit :: (recommended for clarity):
# clean <- function(x) {
#   stringr::str_to_lower(stringr::str_trim(x))
# }
#
# Both work; prefer Option 2 to keep NAMESPACE minimal

devtools::document()のワークフロー

roxygen2コメントを編集したら、devtools::document()（Ctrl+Shift+D）を呼び出してman/*.Rdを再生成し、NAMESPACEを更新します。その後、load_all()の実行後に?addでヘルプページを表示し、正しく見えることを確認します。

# Full documentation cycle:
# 1. Edit roxygen2 comments in R/add.R
# 2. devtools::document()     # regenerate man/ and NAMESPACE
# 3. devtools::load_all()     # reload package
# 4. ?add                     # preview the help page
# 5. devtools::check()        # ensure no documentation errors

複数の関数を1つのページにまとめてドキュメント化する

#' @rdname shared_nameを使用すると、複数の関連する関数を1つのヘルプページにまとめられます。主要な関数には完全なroxygen2ブロックを記述し、補助的な関数には@rdnameと@exportだけを記述します。

# R/arithmetic.R
#
# #' Basic Arithmetic
# #' @param x,y Numeric vectors.
# #' @return A numeric vector.
# #' @examples
# #' add(1, 2); subtract(5, 3)
# #' @export
# add <- function(x, y) x + y
#
# #' @rdname add
# #' @export
# subtract <- function(x, y) x - y

その他の便利なタグ

完全なドキュメントを作成するための、その他のroxygen2タグは次のとおりです。

  • #' @seealso \code{\link{other_fn}} — 相互参照
  • #' @note — 説明の後に追加の注記を記載する
  • #' @author Name — 関数の作成者
  • #' @keywords internal — パッケージインデックスには表示せず、ヘルプページは保持する
  • #' @family group_name — ヘルプ内で関連する関数をグループ化する
# #' Add two numbers
# #' @param x,y Numeric vectors.
# #' @return Numeric vector.
# #' @seealso \code{\link{subtract}} for the inverse operation.
# #' @family arithmetic
# #' @examples
# #' add(1, 1)
# #' @export
# add <- function(x, y) x + y

クイックチェック：@exportタグ

roxygen2のドキュメントはあるものの、#' @exportタグがないRパッケージの関数はどうなりますか？

roxygen2ドキュメントの振り返り

完全なRパッケージドキュメントに必要なroxygen2の主なタグは次のとおりです。

  • #' @title / 1行目 — 関数のタイトル
  • #' @description — 詳細な説明
  • #' @param name Description — 各引数をドキュメント化する
  • #' @return Description — 戻り値を説明する
  • #' @examples \n code — 実行可能な例（R CMD checkで検証される）
  • #' @export — NAMESPACEに追加する（関数を公開する）
  • #' @importFrom pkg fn — 特定の関数をインポートする
  • devtools::document()を実行してman/とNAMESPACEを再生成する

よくある質問

「roxygen2 による関数ドキュメントの作成」レッスンは無料ですか？

はい。「roxygen2 による関数ドキュメントの作成」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、R Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 R Academyコースには全4レッスンが含まれています。

「roxygen2 による関数ドキュメントの作成」で何を学びますか？

@param、@return、@examples、@export タグを記述し、ドキュメントを自動生成します。 ブラウザで直接実行するハンズオンコードでR Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

R Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのR Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。

「roxygen2 による関数ドキュメントの作成」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このR Academyレッスンでコードを書いて実行できますか？

はい。すべてのR Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. usethis と devtools によるパッケージ構成
  2. roxygen2 による関数ドキュメントの作成
  3. testthat による単体テスト
  4. CRAN への提出とパッケージメンテナンス
← R Academyに戻る