0Pricing
R Academy · Lekcja

Dokumentowanie funkcji za pomocą roxygen2

Pisz tagi @param, @return, @examples i @export, aby automatycznie generować dokumentację.

Dokumentowanie funkcji za pomocą roxygen2 to bezpłatna lekcja R Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej R Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs R Academy zawiera 4 lekcji w sumie.

Czym jest roxygen2?

roxygen2 umożliwia bezpośrednie pisanie dokumentacji R nad funkcją w postaci specjalnie sformatowanych komentarzy rozpoczynających się od #'. Po uruchomieniu devtools::document() roxygen2 analizuje te komentarze, generuje pliki man/*.Rd i automatycznie aktualizuje plik NAMESPACE.

Minimalny blok roxygen2

Najprostszy blok dokumentacji musi zawierać co najmniej tytuł i opis. Pierwsze zdanie (do pierwszej kropki lub pustego wiersza) staje się tytułem. Kolejne akapity stają się opisem.

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

Tagi @title i @description

Jawnych tagów @title i @description należy używać, gdy konwencja pierwszego akapitu nie jest wystarczająca — na przykład gdy tytuł ma różnić się od nazwy funkcji lub opis składa się z wielu akapitów.

# #' @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 — dokumentowanie argumentów

#' @param name Description dokumentuje jeden argument funkcji. Należy użyć jednego wiersza @param na argument. Opis powinien określać oczekiwany typ oraz wskazywać, czym steruje dany argument.

# #' 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 — dokumentowanie wartości zwracanej

#' @return Description opisuje wartość zwracaną przez funkcję. Należy podać jej typ, klasę i strukturę. Jest to wymagane przy zgłaszaniu pakietu do 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 — wykonywalne przykłady kodu

#' @examples zawiera kod, który pojawia się na stronie pomocy i jest uruchamiany przez R CMD check. Przykłady muszą kończyć się w czasie krótszym niż 5 sekund i nie mogą wymagać zewnętrznych zasobów (sieci ani plików). Każdy wiersz to zwykły kod R — nie trzeba stosować żadnych specjalnych prefiksów.

# #' 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 — udostępnianie funkcji publicznie

#' @export informuje roxygen2, aby dodać funkcję do NAMESPACE, dzięki czemu staje się ona dostępna dla użytkowników pakietu. Funkcje bez @export są wewnętrzne — można je wywoływać w obrębie pakietu, ale nie przez użytkowników (bez użycia :::).

# 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 — importowanie funkcji

#' @importFrom pkg fn1 fn2 importuje określone funkcje z pakietu do przestrzeni nazw, dzięki czemu można je wywoływać bez prefiksu pkg::. Należy używać tego oszczędnie — jawne pkg::fn() jest bardziej przejrzyste i zapobiega zaśmiecaniu przestrzeni nazw.

# 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

Proces devtools::document()

Po edycji komentarzy roxygen2 należy wywołać devtools::document() (Ctrl+Shift+D), aby ponownie wygenerować man/*.Rd i zaktualizować NAMESPACE. Następnie należy wyświetlić stronę pomocy za pomocą ?add (po load_all()), aby sprawdzić, czy wygląda poprawnie.

# 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

Dokumentowanie wielu funkcji na jednej stronie

Użyj #' @rdname shared_name, aby połączyć wiele powiązanych funkcji na jednej stronie pomocy. Główna funkcja otrzymuje pełny blok roxygen2, a funkcje dodatkowe tylko @rdname i @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

Inne przydatne tagi

Dodatkowe tagi roxygen2 umożliwiające utworzenie kompletnej dokumentacji:

  • #' @seealso \code{\link{other_fn}} — odsyłacz
  • #' @note — dodatkowe uwagi po opisie
  • #' @author Name — autor funkcji
  • #' @keywords internal — ukrywa funkcję w indeksie pakietu, ale zachowuje jej stronę pomocy
  • #' @family group_name — grupuje powiązane funkcje w pomocy
# #' 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

Szybkie sprawdzenie: tag @export

Co dzieje się z funkcją w pakiecie R, która ma dokumentację roxygen2, ale NIE ma tagu #' @export?

Podsumowanie dokumentacji roxygen2

Najważniejsze tagi roxygen2 potrzebne do kompletnej dokumentacji pakietu R:

  • #' @title / pierwszy wiersz — tytuł funkcji
  • #' @description — szczegółowy opis
  • #' @param name Description — dokumentowanie każdego argumentu
  • #' @return Description — opis wartości zwracanej
  • #' @examples \n code — wykonywalne przykłady (sprawdzane przez R CMD check)
  • #' @export — dodanie do NAMESPACE (upublicznienie funkcji)
  • #' @importFrom pkg fn — importowanie określonych funkcji
  • Uruchomienie devtools::document() w celu ponownego wygenerowania man/ i NAMESPACE

Często zadawane pytania

Czy lekcja „Dokumentowanie funkcji za pomocą roxygen2” jest bezpłatna?

Tak — pełny tekst „Dokumentowanie funkcji za pomocą roxygen2” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu R Academy, przejdź na CoddyKit PRO. Kurs R Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Dokumentowanie funkcji za pomocą roxygen2”?

Pisz tagi @param, @return, @examples i @export, aby automatycznie generować dokumentację. Ćwiczysz R Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć R Academy?

Nie wymagamy żadnego doświadczenia. R Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Dokumentowanie funkcji za pomocą roxygen2”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji R Academy?

Tak. Każda lekcja R Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Struktura pakietu za pomocą usethis i devtools
  2. Dokumentowanie funkcji za pomocą roxygen2
  3. Testy jednostkowe za pomocą testthat
  4. Przesyłanie pakietu do CRAN i jego utrzymanie
← Powrót do R Academy