Roxygen-Dokumentation schreiben

Vollstaendige roxygen2-Dokumentation fuer Funktionen, Datensaetze und Klassen eines R-Pakets erstellen.

Wann verwenden

• Dokumentation zu einer neuen exportierten Funktion hinzufuegen
• Interne Hilfsfunktionen dokumentieren
• Paketdatensaetze dokumentieren
• S3/S4/R6-Klassen und -Methoden dokumentieren
• Dokumentationsbezogene

  R CMD check

  -Hinweise beheben

Eingaben

• Erforderlich: Zu dokumentierende R-Funktion, Datensatz oder Klasse
• Optional: Verwandte Funktionen fuer Querverweise (

  @family

  ,

  @seealso

  )
• Optional: Ob die Funktion exportiert werden soll

Vorgehensweise

Schritt 1: Funktionsdokumentation schreiben

Roxygen-Kommentare direkt oberhalb der Funktion platzieren:

#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
  # implementation
}

Erwartet: Vollstaendiger Roxygen-Block mit Titel, Beschreibung,

@param

@return

@examples

@export

Bei Fehler: Bei Unsicherheit ueber ein Tag

?roxygen2::rd_roclet

@return

Schritt 2: Referenz der wesentlichen Tags

#' Title

#' Description

@param

@return

@examples

@export

@family

@seealso

@keywords internal

Erwartet: Alle erforderlichen Tags fuer den Funktionstyp sind identifiziert. Exportierte Funktionen haben mindestens

@param

@return

@examples

@export

Bei Fehler: Bei unbekannten Tags die roxygen2-Dokumentation fuer Verwendung und Syntax konsultieren.

Schritt 3: Datensaetze dokumentieren

R/data.R

#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#'   \item{date}{Date of observation}
#'   \item{city}{City name}
#'   \item{temp_c}{Temperature in Celsius}
#'   \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"

Erwartet:

R/data.R

@format

@source

Bei Fehler: Wenn

R CMD check

"city_temperatures"

usethis::use_data()

Schritt 4: Das Paket dokumentieren

R/packagename-package.R

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

Erwartet:

R/packagename-package.R

@keywords internal

"_PACKAGE"

devtools::document()

man/packagename-package.Rd

Bei Fehler: Wenn

R CMD check

R/<packagename>-package.R

"_PACKAGE"

Schritt 5: Sonderfaelle behandeln

Funktionen mit Punkten im Namen (S3-Methoden):

#' @export
#' @rdname process
process.myclass <- function(x, ...) {
  # S3 method
}

Dokumentation wiederverwenden mit

@inheritParams

#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
  # implementation
}

Keine sichtbare Bindung beheben mit dem

.data

#' @importFrom rlang .data
my_function <- function(df) {
  dplyr::filter(df, .data$column > 5)
}

Erwartet: Sonderfaelle (S3-Methoden, vererbte Parameter,

.data

@rdname

@inheritParams

Bei Fehler: Wenn

R CMD check

#' @importFrom rlang .data

utils::globalVariables()

Schritt 6: Dokumentation generieren

devtools::document()

Erwartet:

man/

.Rd

NAMESPACE

Bei Fehler: Auf Roxygen-Syntaxfehler pruefen. Haeufige Probleme: nicht geschlossene Klammern in

\describe{}

#'

devtools::document()

Validierung

• Jede exportierte Funktion hat

  @param

  ,

  @return

  und

  @examples

• devtools::document()

  laeuft ohne Fehler

• devtools::check()

  zeigt keine Dokumentationswarnungen

• @family

  -Tags gruppieren verwandte Funktionen korrekt
• Beispiele laufen ohne Fehler (testen mit

  devtools::run_examples()

  )

Haeufige Stolperfallen

• Fehlendes

  @return

  : CRAN erfordert, dass alle exportierten Funktionen ihren Rueckgabewert dokumentieren
• Beispiele, die Internet/Authentifizierung benoetigen: In

  \dontrun{}

  einschliessen mit einem erklaerenden Kommentar
• Langsame Beispiele:

  \donttest{}

  fuer Beispiele verwenden, die funktionieren, aber fuer CRAN zu lange dauern
• Markdown in roxygen: Mit

  Roxygen: list(markdown = TRUE)

  in DESCRIPTION aktivieren

• devtools::document()

  zu laufen vergessen: Man-Pages werden generiert, nicht haendisch geschrieben

Verwandte Skills

• create-r-package

  - erstmalige Paketeinrichtung einschliesslich roxygen-Konfiguration

• write-testthat-tests

  - die dokumentierten Funktionen testen

• write-vignette

  - ausfuehrliche Dokumentation jenseits der Funktionsreferenz

• submit-to-cran

  - Dokumentationsanforderungen fuer CRAN