R Academy · Pelajaran

Mendokumentasikan Fungsi dengan roxygen2

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

Pelajaran 2 daripada 413 langkah

Mendokumentasikan Fungsi dengan roxygen2 ialah pelajaran R Academy percuma di CoddyKit. Ini ialah pelajaran 2 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran R Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus R Academy merangkumi sejumlah 4 pelajaran.

Apakah roxygen2?

roxygen2 membolehkan anda menulis dokumentasi R secara langsung di atas fungsi sebagai ulasan berformat khas yang bermula dengan #'. Apabila anda menjalankan devtools::document(), roxygen2 menghuraikan ulasan ini, menjana fail man/*.Rd dan mengemas kini NAMESPACE secara automatik.

Blok roxygen2 Minimum

Blok dokumentasi paling ringkas memerlukan sekurang-kurangnya tajuk dan perihalan. Ayat pertama (sehingga noktah pertama atau baris kosong) menjadi tajuk. Perenggan seterusnya menjadi perihalan.

# 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 @title dan @description yang jelas apabila konvensyen perenggan pertama tidak mencukupi — contohnya, apabila tajuk perlu berbeza daripada nama fungsi atau perihalan terdiri daripada beberapa perenggan.

# #' @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 bagi setiap argumen. Perihalan hendaklah menyatakan jenis yang dijangka dan perkara yang dikawal 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 Pulangan

#' @return Description menerangkan perkara yang dipulangkan oleh fungsi. Nyatakan jenis, kelas dan struktur nilai pulangan. Ini diperlukan untuk penyerahan kepada 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 Kod yang Boleh Dijalankan

#' @examples menyediakan kod yang muncul pada halaman bantuan dan dijalankan oleh R CMD check. Contoh hendaklah selesai dalam masa kurang daripada 5 saat dan tidak memerlukan sumber luaran (rangkaian, fail). Setiap baris ialah kod R biasa — tiada awalan khas diperlukan.

# #' 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 Umum

#' @export memberitahu roxygen2 supaya menambah fungsi itu kepada NAMESPACE, lalu menjadikannya tersedia kepada pengguna pakej anda. Fungsi tanpa @export adalah dalaman — fungsi tersebut boleh dipanggil dalam pakej tetapi bukan 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 — Mengimport Fungsi

#' @importFrom pkg fn1 fn2 mengimport fungsi tertentu daripada sesuatu pakej ke dalam ruang nama anda supaya anda boleh memanggilnya tanpa awalan pkg::. Gunakan secara berhemat — pkg::fn() yang jelas lebih mudah difahami dan mengelakkan 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

Aliran Kerja devtools::document()

Selepas menyunting ulasan roxygen2, panggil devtools::document() (Ctrl+Shift+D) untuk menjana semula man/*.Rd dan mengemas kini NAMESPACE. Kemudian lihat halaman bantuan dengan ?add (selepas load_all()) untuk memastikan paparannya betul.

# 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 berkaitan pada satu halaman bantuan. Fungsi utama mendapat blok roxygen2 penuh; fungsi sekunder hanya mendapat @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 Lain

Tag roxygen2 tambahan untuk dokumentasi lengkap:

#' @seealso \code{\link{other_fn}} — rujukan silang
#' @note — nota tambahan selepas perihalan
#' @author Name — pengarang fungsi
#' @keywords internal — menyembunyikan daripada indeks pakej tetapi mengekalkan halaman bantuan
#' @family group_name — mengumpulkan fungsi berkaitan 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

Semakan Pantas: Tag @export

Apakah yang berlaku kepada fungsi dalam pakej R yang mempunyai dokumentasi roxygen2 tetapi TIADA tag #' @export?

Jawab dalam pelajaran interaktif

Imbas Kembali Dokumentasi roxygen2

Tag teras roxygen2 untuk dokumentasi pakej R yang lengkap:

#' @title / baris pertama — tajuk fungsi
#' @description — perihalan terperinci
#' @param name Description — dokumentasikan setiap argumen
#' @return Description — terangkan nilai pulangan
#' @examples \n code — contoh yang boleh dijalankan (diperiksa oleh R CMD check)
#' @export — tambah kepada NAMESPACE (menjadikan fungsi umum)
#' @importFrom pkg fn — import fungsi tertentu
Jalankan devtools::document() untuk menjana semula man/ dan NAMESPACE

Percuma untuk bermula

Pelajari R dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 43
Pelajaran: 159

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Mendokumentasikan Fungsi dengan roxygen2” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran R Academy, termasuk “Mendokumentasikan Fungsi dengan roxygen2”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus R Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Mendokumentasikan Fungsi dengan roxygen2”?

Tulis tag @param, @return, @examples dan @export untuk dokumentasi automatik. Anda berlatih R Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan R Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran R Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 2 daripada 4.

Berapa lamakah pelajaran “Mendokumentasikan Fungsi dengan roxygen2” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran R Academy ini?

Ya. Setiap pelajaran R Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

Struktur Pakej dengan usethis dan devtools
Mendokumentasikan Fungsi dengan roxygen2
Ujian Unit dengan testthat
Penyerahan CRAN dan Penyelenggaraan Pakej

← Kembali ke R Academy