R Academy · Lezione

Documentazione delle funzioni con roxygen2

Scriva i tag @param, @return, @examples e @export per generare automaticamente la documentazione

Lezione 2 di 413 passaggi

Documentazione delle funzioni con roxygen2 è una lezione R Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento R Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso R Academy include 4 lezioni in totale.

Che cos'è roxygen2?

roxygen2 consente di scrivere la documentazione R direttamente sopra la funzione, come commenti con una formattazione specifica che iniziano con #'. Quando esegue devtools::document(), roxygen2 analizza questi commenti, genera i file man/*.Rd e aggiorna automaticamente NAMESPACE.

Il blocco roxygen2 minimo

Il blocco di documentazione più semplice richiede almeno un titolo e una descrizione. La prima frase (fino al primo punto o alla prima riga vuota) diventa il titolo. I paragrafi successivi diventano la descrizione.

# 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 e @description

Usi i tag espliciti @title e @description quando la convenzione del primo paragrafo non è sufficiente, ad esempio quando il titolo deve essere diverso dal nome della funzione o la descrizione è composta da più paragrafi.

# #' @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 — Documentazione degli argomenti

#' @param name Description documenta un argomento della funzione. Usi una riga @param per ogni argomento. La descrizione dovrebbe indicare il tipo previsto e l'effetto dell'argomento.

# #' 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 — Documentazione del valore restituito

#' @return Description descrive ciò che restituisce la funzione. Indichi il tipo, la classe e la struttura del valore restituito. È obbligatorio per la pubblicazione su 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 — Esempi di codice eseguibili

#' @examples fornisce codice che appare nella pagina della guida e viene eseguito da R CMD check. Gli esempi devono terminare in meno di 5 secondi e non devono richiedere risorse esterne (rete, file). Ogni riga è normale codice R: non sono necessari prefissi speciali.

# #' 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 — Rendere pubbliche le funzioni

#' @export indica a roxygen2 di aggiungere la funzione a NAMESPACE, rendendola disponibile agli utenti del pacchetto. Le funzioni senza @export sono interne: possono essere chiamate all'interno del pacchetto, ma non dagli utenti (senza :::).

# 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 — Importazione di funzioni

#' @importFrom pkg fn1 fn2 importa funzioni specifiche da un pacchetto nel proprio spazio dei nomi, così da poterle chiamare senza il prefisso pkg::. Lo usi con parsimonia: pkg::fn() esplicito è più chiaro ed evita di inquinare lo spazio dei nomi.

# 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

Flusso di lavoro di devtools::document()

Dopo aver modificato i commenti roxygen2, chiami devtools::document() (Ctrl+Shift+D) per rigenerare man/*.Rd e aggiornare NAMESPACE. Visualizzi quindi la pagina della guida con ?add (dopo load_all()) per verificare che sia corretta.

# 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

Documentazione di più funzioni nella stessa pagina

Usi #' @rdname shared_name per riunire più funzioni correlate in un'unica pagina della guida. La funzione principale riceve il blocco roxygen2 completo; le funzioni secondarie ricevono solo @rdname e @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

Altri tag utili

Altri tag roxygen2 per una documentazione completa:

#' @seealso \code{\link{other_fn}} — riferimento incrociato
#' @note — note aggiuntive dopo la descrizione
#' @author Name — autore della funzione
#' @keywords internal — nasconde la funzione dall'indice del pacchetto, mantenendo però la pagina della guida
#' @family group_name — raggruppa le funzioni correlate nella guida

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

Verifica rapida: tag @export

Che cosa accade a una funzione di un pacchetto R che dispone della documentazione roxygen2 ma NON del tag #' @export?

Rispondi nella lezione interattiva

Riepilogo della documentazione roxygen2

Tag roxygen2 fondamentali per una documentazione completa dei pacchetti R:

#' @title / prima riga — titolo della funzione
#' @description — descrizione dettagliata
#' @param name Description — documenta ogni argomento
#' @return Description — descrive il valore restituito
#' @examples \n code — esempi eseguibili (controllati da R CMD check)
#' @export — aggiunge la funzione a NAMESPACE (rendendola pubblica)
#' @importFrom pkg fn — importa funzioni specifiche
Esegua devtools::document() per rigenerare man/ e NAMESPACE

Gratis per iniziare

Impara R con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 43
Lezioni: 159

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Documentazione delle funzioni con roxygen2» è gratuita?

Sì — il testo completo di «Documentazione delle funzioni con roxygen2» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso R Academy, passa a CoddyKit PRO. Il corso R Academy include 4 lezioni in totale.

Cosa imparerò in «Documentazione delle funzioni con roxygen2»?

Scriva i tag @param, @return, @examples e @export per generare automaticamente la documentazione Eserciti R Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare R Academy?

Non è richiesta alcuna esperienza precedente. R Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Documentazione delle funzioni con roxygen2»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione R Academy?

Sì. Ogni lezione R Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Struttura dei pacchetti con usethis e devtools
Documentazione delle funzioni con roxygen2
Test unitari con testthat
Invio a CRAN e manutenzione dei pacchetti

← Torna a R Academy