0Pricing
R Academy · Lektion

Funktionen mit roxygen2 dokumentieren

Schreiben Sie @param-, @return-, @examples- und @export-Tags für eine automatische Dokumentation

Funktionen mit roxygen2 dokumentieren ist eine kostenlose R Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des R Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der R Academy-Kurs umfasst insgesamt 4 Lektionen.

Was ist roxygen2?

Mit roxygen2 können Sie die R-Dokumentation direkt über Ihrer Funktion als speziell formatierte Kommentare schreiben, die mit #' beginnen. Wenn Sie devtools::document() ausführen, analysiert roxygen2 diese Kommentare, generiert man/*.Rd-Dateien und aktualisiert NAMESPACE automatisch.

Der minimale roxygen2-Block

Der einfachste Dokumentationsblock benötigt mindestens einen Titel und eine Beschreibung. Der erste Satz (bis zum ersten Punkt oder zur ersten Leerzeile) wird zum Titel. Nachfolgende Absätze werden zur Beschreibung.

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

Die Tags @title und @description

Verwenden Sie explizite Tags @title und @description, wenn die Konvention mit dem ersten Absatz nicht ausreicht — zum Beispiel, wenn sich der Titel vom Funktionsnamen unterscheiden muss oder die Beschreibung aus mehreren Absätzen besteht.

# #' @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 — Argumente dokumentieren

#' @param name Description dokumentiert ein Funktionsargument. Verwenden Sie pro Argument eine @param-Zeile. Die Beschreibung sollte den erwarteten Typ und die Wirkung des Arguments angeben.

# #' 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 — Rückgabewert dokumentieren

#' @return Description beschreibt, was die Funktion zurückgibt. Geben Sie Typ, Klasse und Struktur des Rückgabewerts an. Dies ist für die Einreichung bei CRAN erforderlich.

# #' 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 — Ausführbare Codebeispiele

#' @examples stellt Code bereit, der auf der Hilfeseite erscheint und von R CMD check ausgeführt wird. Beispiele müssen in weniger als 5 Sekunden abgeschlossen sein und dürfen keine externen Ressourcen (Netzwerk, Dateien) benötigen. Jede Zeile ist gewöhnlicher R-Code — spezielle Präfixe sind nicht erforderlich.

# #' 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 — Funktionen öffentlich machen

#' @export weist roxygen2 an, die Funktion zu NAMESPACE hinzuzufügen, sodass sie für Benutzer Ihres Pakets verfügbar ist. Funktionen ohne @export sind intern — sie können innerhalb des Pakets, aber nicht von Benutzern aufgerufen werden (außer mit :::).

# 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 — Funktionen importieren

#' @importFrom pkg fn1 fn2 importiert bestimmte Funktionen aus einem Paket in Ihren Namespace, sodass Sie sie ohne das Präfix pkg:: aufrufen können. Verwenden Sie dies sparsam — der explizite Aufruf pkg::fn() ist übersichtlicher und vermeidet eine Verschmutzung des 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

Workflow mit devtools::document()

Rufen Sie nach dem Bearbeiten von roxygen2-Kommentaren devtools::document() (Strg+Umschalt+D) auf, um man/*.Rd neu zu generieren und NAMESPACE zu aktualisieren. Sehen Sie sich anschließend die Hilfeseite mit ?add (nach load_all()) an, um zu bestätigen, dass sie korrekt aussieht.

# 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

Mehrere Funktionen auf einer Seite dokumentieren

Verwenden Sie #' @rdname shared_name, um mehrere verwandte Funktionen auf einer einzigen Hilfeseite zusammenzufassen. Die primäre Funktion erhält den vollständigen roxygen2-Block; sekundäre Funktionen erhalten nur @rdname und @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

Weitere nützliche Tags

Zusätzliche roxygen2-Tags für eine vollständige Dokumentation:

  • #' @seealso \code{\link{other_fn}} — Querverweis
  • #' @note — zusätzliche Hinweise nach der Beschreibung
  • #' @author Name — Autor der Funktion
  • #' @keywords internal — blendet die Funktion aus dem Paketindex aus, behält aber die Hilfeseite bei
  • #' @family group_name — gruppiert verwandte Funktionen in der Hilfe
# #' 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

Schnelltest: @export-Tag

Was geschieht mit einer Funktion in einem R-Paket, die über eine roxygen2-Dokumentation, aber über KEIN #' @export-Tag verfügt?

Rückblick auf die roxygen2-Dokumentation

Zentrale roxygen2-Tags für eine vollständige Dokumentation von R-Paketen:

  • #' @title / erste Zeile — Funktionstitel
  • #' @description — ausführliche Beschreibung
  • #' @param name Description — jedes Argument dokumentieren
  • #' @return Description — Rückgabewert beschreiben
  • #' @examples \n code — ausführbare Beispiele (von R CMD check geprüft)
  • #' @export — zu NAMESPACE hinzufügen (macht die Funktion öffentlich)
  • #' @importFrom pkg fn — bestimmte Funktionen importieren
  • devtools::document() ausführen, um man/ und NAMESPACE neu zu generieren

Häufig gestellte Fragen

Ist die Lektion „Funktionen mit roxygen2 dokumentieren“ kostenlos?

Ja — der vollständige Text von „Funktionen mit roxygen2 dokumentieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des R Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der R Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Funktionen mit roxygen2 dokumentieren“?

Schreiben Sie @param-, @return-, @examples- und @export-Tags für eine automatische Dokumentation Du übst R Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um R Academy zu starten?

Keine Vorkenntnisse erforderlich. R Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Funktionen mit roxygen2 dokumentieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser R Academy-Lektion Code schreiben und ausführen?

Ja. Jede R Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

  1. Paketstruktur mit usethis und devtools
  2. Funktionen mit roxygen2 dokumentieren
  3. Unit-Tests mit testthat
  4. CRAN-Einreichung und Paketpflege
← Zurück zu R Academy