0Pricing
R Academy · Pelajaran

Mendokumentasikan Fungsi dengan roxygen2

Tulis tag @param, @return, @examples, dan @export untuk dokumentasi otomatis.

Mendokumentasikan Fungsi dengan roxygen2 adalah pelajaran R Academy gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar R Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus R Academy mencakup 4 pelajaran total.

Apa Itu roxygen2?

roxygen2 memungkinkan Anda menulis dokumentasi R langsung di atas fungsi sebagai komentar berformat khusus yang diawali #'. Saat menjalankan devtools::document(), roxygen2 mengurai komentar tersebut, membuat file man/*.Rd, dan memperbarui NAMESPACE secara otomatis.

Blok Minimal roxygen2

Blok dokumentasi paling sederhana setidaknya memerlukan judul dan deskripsi. Kalimat pertama (hingga titik pertama atau baris kosong) menjadi judul. Paragraf-paragraf berikutnya menjadi deskripsi.

# 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
# }

Tag @title dan @description

Gunakan tag eksplisit @title dan @description ketika konvensi paragraf pertama tidak memadai — misalnya, ketika judul harus berbeda dari nama fungsi atau deskripsinya terdiri dari beberapa paragraf.

# #' @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 — Mendokumentasikan Argumen

#' @param name Description mendokumentasikan satu argumen fungsi. Gunakan satu baris @param untuk setiap argumen. Deskripsi harus menyatakan tipe yang diharapkan dan hal yang dikendalikan oleh argumen tersebut.

# #' 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 — Mendokumentasikan Nilai Kembalian

#' @return Description menjelaskan hal yang dikembalikan fungsi. Nyatakan tipe, kelas, dan struktur nilai kembalian. Hal ini diperlukan untuk pengajuan ke 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 — Contoh Kode yang Dapat Dijalankan

#' @examples menyediakan kode yang muncul di halaman bantuan dan dijalankan oleh R CMD check. Contoh harus selesai dalam waktu kurang dari 5 detik dan tidak boleh memerlukan sumber daya eksternal (jaringan, file). Setiap baris adalah kode R biasa — tidak diperlukan awalan khusus.

# #' 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 — Menjadikan Fungsi Publik

#' @export memberi tahu roxygen2 untuk menambahkan fungsi ke NAMESPACE, sehingga fungsi tersebut tersedia bagi pengguna paket Anda. Fungsi tanpa @export bersifat internal — fungsi tersebut dapat dipanggil dari dalam paket, tetapi tidak oleh pengguna (tanpa :::).

# 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 — Mengimpor Fungsi

#' @importFrom pkg fn1 fn2 mengimpor fungsi tertentu dari sebuah paket ke ruang nama Anda, sehingga Anda dapat memanggilnya tanpa awalan pkg::. Gunakan seperlunya — pkg::fn() yang eksplisit lebih jelas dan mencegah pencemaran ruang nama.

# 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

Alur Kerja devtools::document()

Setelah mengedit komentar roxygen2, panggil devtools::document() (Ctrl+Shift+D) untuk membuat ulang man/*.Rd dan memperbarui NAMESPACE. Kemudian lihat halaman bantuan dengan ?add (setelah load_all()) untuk memastikan tampilannya benar.

# 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

Mendokumentasikan Beberapa Fungsi pada Satu Halaman

Gunakan #' @rdname shared_name untuk menggabungkan beberapa fungsi terkait ke dalam satu halaman bantuan. Fungsi utama mendapatkan blok roxygen2 lengkap; fungsi sekunder hanya mendapatkan @rdname dan @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

Tag Berguna Lainnya

Tag roxygen2 tambahan untuk dokumentasi lengkap:

  • #' @seealso \code{\link{other_fn}} — rujuk silang
  • #' @note — catatan tambahan setelah deskripsi
  • #' @author Name — penulis fungsi
  • #' @keywords internal — menyembunyikan fungsi dari indeks paket, tetapi mempertahankan halaman bantuannya
  • #' @family group_name — mengelompokkan fungsi terkait dalam bantuan
# #' 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

Pemeriksaan Singkat: Tag @export

Apa yang terjadi pada fungsi dalam paket R yang memiliki dokumentasi roxygen2 tetapi TIDAK memiliki tag #' @export?

Rangkuman Dokumentasi roxygen2

Tag inti roxygen2 untuk dokumentasi paket R yang lengkap:

  • #' @title / baris pertama — judul fungsi
  • #' @description — deskripsi terperinci
  • #' @param name Description — mendokumentasikan setiap argumen
  • #' @return Description — menjelaskan nilai kembalian
  • #' @examples \n code — contoh yang dapat dijalankan (diperiksa oleh R CMD check)
  • #' @export — menambahkan ke NAMESPACE (menjadikan fungsi publik)
  • #' @importFrom pkg fn — mengimpor fungsi tertentu
  • Jalankan devtools::document() untuk membuat ulang man/ dan NAMESPACE

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Mendokumentasikan Fungsi dengan roxygen2” gratis?

Ya — teks lengkap “Mendokumentasikan Fungsi dengan roxygen2” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus R Academy, upgrade ke CoddyKit PRO. Kursus R Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Mendokumentasikan Fungsi dengan roxygen2”?

Tulis tag @param, @return, @examples, dan @export untuk dokumentasi otomatis. Kamu berlatih R Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai R Academy?

Tidak diperlukan pengalaman sebelumnya. R Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Mendokumentasikan Fungsi dengan roxygen2” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran R Academy ini?

Ya. Setiap pelajaran R Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

  1. Struktur Paket dengan usethis dan devtools
  2. Mendokumentasikan Fungsi dengan roxygen2
  3. Pengujian Unit dengan testthat
  4. Pengiriman ke CRAN dan Pemeliharaan Paket
← Kembali ke R Academy