R Academy · Lektion

Dokumentation af funktioner med roxygen2

Skriv tags som @param, @return, @examples og @export til automatisk dokumentation.

Lektion 2 af 413 trin

Dokumentation af funktioner med roxygen2 er en gratis R Academy-lektion på CoddyKit. Dette er lektion 2 af 4. Du kan læse alle 3 lektioner i dette læringsspor gratis i deres fulde længde — derefter låser CoddyKit PRO alle lektioner op samt praktiske øvelser med en indbygget kodeeditor og en AI-underviser døgnet rundt. Den er en del af læringsforløbet i R Academy, og dine fremskridt synkroniseres på tværs af nettet og CoddyKit-appen. R Academy-kurset indeholder 4 lektioner i alt.

Hvad er roxygen2?

roxygen2 lader dig skrive R-dokumentation direkte over din funktion som særligt formaterede kommentarer, der begynder med #'. Når du kører devtools::document(), fortolker roxygen2 disse kommentarer og genererer man/*.Rd-filer samt opdaterer NAMESPACE automatisk.

Den minimale roxygen2-blok

Den enkleste dokumentationsblok skal mindst indeholde en titel og en beskrivelse. Den første sætning (frem til det første punktum eller den første tomme linje) bliver titlen. De efterfølgende afsnit bliver beskrivelsen.

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

Taggene @title og @description

Brug de eksplicitte tags @title og @description, når konventionen med det første afsnit ikke er tilstrækkelig — for eksempel når titlen skal være forskellig fra funktionsnavnet, eller når beskrivelsen består af flere afsnit.

# #' @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 — dokumentation af argumenter

#' @param name Description dokumenterer ét funktionsargument. Brug én @param-linje pr. argument. Beskrivelsen bør angive den forventede type og, hvad argumentet styrer.

# #' 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 — dokumentation af returværdien

#' @return Description beskriver, hvad funktionen returnerer. Angiv returværdiens type, klasse og struktur. Dette er påkrævet ved indsendelse til 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 — kørbare kodeeksempler

#' @examples indeholder kode, der vises på hjælpesiden og køres af R CMD check. Eksempler skal være færdige på under 5 sekunder og må ikke kræve eksterne ressourcer (netværk, filer). Hver linje er almindelig R-kode — der kræves ingen særlige præfikser.

# #' 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 — gør funktioner offentlige

#' @export fortæller roxygen2, at funktionen skal tilføjes til NAMESPACE, så den bliver tilgængelig for brugere af din pakke. Funktioner uden @export er interne — de kan kaldes i pakken, men ikke af brugere (uden :::).

# 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 — import af funktioner

#' @importFrom pkg fn1 fn2 importerer bestemte funktioner fra en pakke til dit namespace, så du kan kalde dem uden præfikset pkg::. Brug det med omtanke — eksplicit pkg::fn() er tydeligere og undgår forurening af namespace.

# 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

Arbejdsgangen med devtools::document()

Efter redigering af roxygen2-kommentarer skal du kalde devtools::document() (Ctrl+Shift+D) for at generere man/*.Rd igen og opdatere NAMESPACE. Se derefter hjælpesiden med ?add (efter load_all()) for at bekræfte, at den ser korrekt ud.

# 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

Dokumentation af flere funktioner på én side

Brug #' @rdname shared_name til at samle flere relaterede funktioner på én hjælpeside. Den primære funktion får hele roxygen2-blokken; sekundære funktioner får kun @rdname og @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

Andre nyttige tags

Yderligere roxygen2-tags til komplet dokumentation:

#' @seealso \code{\link{other_fn}} — krydshenvisning
#' @note — ekstra noter efter beskrivelsen
#' @author Name — funktionens forfatter
#' @keywords internal — skjuler funktionen fra pakkeindekset, men bevarer hjælpesiden
#' @family group_name — grupperer relaterede funktioner i hjælpen

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

Hurtigt tjek: @export-tagget

Hvad sker der med en funktion i en R-pakke, som har roxygen2-dokumentation, men INGEN #' @export-tag?

Besvar den i den interaktive lektion

Opsummering af roxygen2-dokumentation

Centrale roxygen2-tags til komplet dokumentation af R-pakker:

#' @title / første linje — funktionens titel
#' @description — detaljeret beskrivelse
#' @param name Description — dokumentér hvert argument
#' @return Description — beskriv returværdien
#' @examples \n code — kørbare eksempler (kontrolleres af R CMD check)
#' @export — tilføj til NAMESPACE (gør funktionen offentlig)
#' @importFrom pkg fn — importér bestemte funktioner
Kør devtools::document() for at generere man/ og NAMESPACE igen

Gratis at komme i gang

Lær R med en AI-underviser — gratis

Skriv og kør rigtig kode i din browser, få øjeblikkelig hjælp fra en AI-underviser døgnet rundt, og fortsæt, hvor du slap, på web eller i appen.

Kurser: 43
Lektioner: 159

Start gratis Se hele kurset

Ofte stillede spørgsmål

Er lektionen “Dokumentation af funktioner med roxygen2” gratis?

Ja — alle 3 lektioner i læringssporet R Academy, inklusive “Dokumentation af funktioner med roxygen2”, kan læses gratis i deres fulde længde her på webstedet. Derefter låser CoddyKit PRO alle lektioner op samt interaktive øvelser med en indbygget kodeeditor og en AI-underviser døgnet rundt. R Academy-kurset indeholder 4 lektioner i alt.

Hvad lærer jeg i “Dokumentation af funktioner med roxygen2”?

Skriv tags som @param, @return, @examples og @export til automatisk dokumentation. Du øver dig i R Academy med praktisk kode, som du kører direkte i browseren, og en AI-vejleder døgnet rundt besvarer dine spørgsmål, mens du arbejder dig gennem lektionen.

Skal jeg have erfaring for at begynde på R Academy?

Der kræves ingen tidligere erfaring. R Academy på CoddyKit er tilrettelagt for både begyndere og øvede, så du kan starte her eller fra begyndelsen og lære i dit eget tempo. Dette er lektion 2 af 4.

Hvor lang tid tager lektionen “Dokumentation af funktioner med roxygen2”?

De fleste CoddyKit-lektioner tager cirka 5–10 minutter. Hver lektion er kort og interaktiv, så du gør løbende fremskridt og kan fortsætte, hvor du slap – på både web og app.

Kan jeg skrive og køre kode i denne R Academy-lektion?

Ja. Alle R Academy-lektioner har en indbygget kodeeditor, så du kan skrive og køre rigtig kode direkte i din browser og få øjeblikkelig feedback fra AI – uden lokal opsætning.

Alle lektioner i dette kursus

Pakkestruktur med usethis og devtools
Dokumentation af funktioner med roxygen2
Enhedstest med testthat
CRAN-indsendelse og vedligeholdelse af pakker

← Tilbage til R Academy