R Academy · Ders

roxygen2 ile İşlevleri Belgeleme

Otomatik belgeler için @param, @return, @examples ve @export etiketlerini yazın.

roxygen2 ile İşlevleri Belgeleme, CoddyKit'te ücretsiz bir R Academy dersidir. Bu, 4 dersinin 2. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, R Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. R Academy kursu toplamda 4 dersten oluşur.

roxygen2 Nedir?

roxygen2, işlevinizin hemen üstüne #' ile başlayan, özel biçimlendirilmiş yorumlar olarak doğrudan R belgeleri yazmanızı sağlar. devtools::document() komutunu çalıştırdığınızda roxygen2 bu yorumları ayrıştırır, man/*.Rd dosyalarını oluşturur ve NAMESPACE dosyasını otomatik olarak günceller.

En Basit roxygen2 Bloğu

En basit belge bloğunda en az bir başlık ve açıklama bulunmalıdır. İlk cümle (ilk noktaya veya boş satıra kadar olan bölüm) başlık olur. Sonraki paragraflar açıklamayı oluşturur.

# 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 ve @description Etiketleri

İlk paragraf kuralı yeterli olmadığında açıkça @title ve @description etiketlerini kullanın; örneğin başlığın işlev adından farklı olması gerektiğinde veya açıklama birden fazla paragraftan oluştuğunda.

# #' @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 — Bağımsız Değişkenleri Belgeleme

#' @param name Description, bir işlev bağımsız değişkenini belgeler. Her bağımsız değişken için bir @param satırı kullanın. Açıklama, beklenen türü ve bağımsız değişkenin neyi denetlediğini belirtmelidir.

# #' 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 — Döndürülen Değeri Belgeleme

#' @return Description, işlevin ne döndürdüğünü açıklar. Döndürülen değerin türünü, sınıfını ve yapısını belirtin. Bu, CRAN'a gönderim için gereklidir.

# #' 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 — Çalıştırılabilir Kod Örnekleri

#' @examples, yardım sayfasında görünen ve R CMD check tarafından çalıştırılan kodu sağlar. Örnekler 5 saniyeden kısa sürede tamamlanmalı ve harici kaynaklar (ağ, dosyalar) gerektirmemelidir. Her satır normal R kodudur; özel ön ekler gerekmez.

# #' 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 — İşlevleri Herkese Açma

#' @export, roxygen2'ye işlevi NAMESPACE dosyasına eklemesini ve böylece paketinizin kullanıcıları tarafından kullanılabilir olmasını söyler. @export içermeyen işlevler içseldir; paket içinde çağrılabilir, ancak kullanıcılar tarafından (::: olmadan) çağrılamaz.

# 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 — İşlevleri İçe Aktarma

#' @importFrom pkg fn1 fn2, belirli işlevleri bir paketten ad alanınıza aktarır; böylece bunları pkg:: ön eki olmadan çağırabilirsiniz. Bunu ölçülü kullanın; açıkça yazılan pkg::fn() daha anlaşılırdır ve ad alanının kirlenmesini önler.

# 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() İş Akışı

roxygen2 yorumlarını düzenledikten sonra devtools::document() (Ctrl+Shift+D) komutunu çağırarak man/*.Rd dosyalarını yeniden oluşturun ve NAMESPACE dosyasını güncelleyin. Ardından doğru göründüğünü doğrulamak için load_all() sonrasında yardım sayfasını ?add ile görüntüleyin.

# 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

Bir Sayfada Birden Çok İşlevi Belgeleme

Birbiriyle ilişkili birden çok işlevi tek bir yardım sayfasında birleştirmek için #' @rdname shared_name kullanın. Birincil işlev tam roxygen2 bloğunu alır; ikincil işlevler yalnızca @rdname ve @export alır.

# 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

Diğer Kullanışlı Etiketler

Tam bir belgeleme için ek roxygen2 etiketleri:

#' @seealso \code{\link{other_fn}} — çapraz başvuru
#' @note — açıklamadan sonra ek notlar
#' @author Name — işlevin yazarı
#' @keywords internal — yardım sayfasını koruyup paket dizininden gizler
#' @family group_name — yardım içinde ilişkili işlevleri gruplar

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

Hızlı Kontrol: @export Etiketi

roxygen2 belgelerine sahip ancak #' @export etiketi OLMAYAN bir R paketi işlevine ne olur?

roxygen2 Belgelerinin Özeti

Tam R paketi belgeleri için temel roxygen2 etiketleri:

#' @title / ilk satır — işlev başlığı
#' @description — ayrıntılı açıklama
#' @param name Description — her bağımsız değişkeni belgeler
#' @return Description — döndürülen değeri açıklar
#' @examples \n code — çalıştırılabilir örnekler (R CMD check tarafından denetlenir)
#' @export — NAMESPACE'a ekler (işlevi herkese açık yapar)
#' @importFrom pkg fn — belirli işlevleri içe aktarır
man/ ve NAMESPACE'ı yeniden oluşturmak için devtools::document() komutunu çalıştırın

Sıkça Sorulan Sorular

“roxygen2 ile İşlevleri Belgeleme” dersi ücretsiz mi?

Evet — “roxygen2 ile İşlevleri Belgeleme” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve R Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. R Academy kursu toplamda 4 dersten oluşur.

“roxygen2 ile İşlevleri Belgeleme” dersinde ne öğreneceğim?

Otomatik belgeler için @param, @return, @examples ve @export etiketlerini yazın. R Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

R Academy öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te R Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 2. dersidir.

“roxygen2 ile İşlevleri Belgeleme” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu R Academy dersinde kod yazıp çalıştırabilir miyim?

Evet. Her R Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

← R Academy Sayfasına Dön