0Pricing
R Academy · Leçon

Documenter des fonctions avec roxygen2

Rédigez les balises @param, @return, @examples et @export pour générer automatiquement la documentation.

Documenter des fonctions avec roxygen2 est une leçon R Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage R Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours R Academy comprend 4 leçons au total.

Qu’est-ce que roxygen2 ?

roxygen2 vous permet d’écrire la documentation R directement au-dessus de votre fonction sous forme de commentaires spécialement formatés commençant par #'. Lorsque vous exécutez devtools::document(), roxygen2 analyse ces commentaires, génère les fichiers man/*.Rd et met automatiquement à jour NAMESPACE.

Le bloc roxygen2 minimal

Le bloc de documentation le plus simple doit au moins comporter un titre et une description. La première phrase (jusqu’au premier point ou à la première ligne vide) devient le titre. Les paragraphes suivants deviennent la description.

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

Balises @title et @description

Utilisez les balises explicites @title et @description lorsque la convention du premier paragraphe ne suffit pas — par exemple lorsque le titre doit différer du nom de la fonction ou lorsque la description comporte plusieurs paragraphes.

# #' @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 — Documenter les arguments

#' @param name Description documente un argument de fonction. Utilisez une ligne @param par argument. La description doit indiquer le type attendu et ce que contrôle l’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 — Documenter la valeur renvoyée

#' @return Description décrit ce que renvoie la fonction. Indiquez le type, la classe et la structure de la valeur renvoyée. Cette balise est requise pour une soumission à 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 — Exemples de code exécutables

#' @examples fournit du code qui apparaît sur la page d’aide et qui est exécuté par R CMD check. Les exemples doivent s’exécuter en moins de 5 secondes et ne pas nécessiter de ressources externes (réseau, fichiers). Chaque ligne est du code R ordinaire : aucun préfixe particulier n’est nécessaire.

# #' 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 — Rendre les fonctions publiques

#' @export indique à roxygen2 d’ajouter la fonction à NAMESPACE, ce qui la rend disponible pour les utilisateurs de votre package. Les fonctions sans @export sont internes : elles peuvent être appelées depuis le package, mais pas par les utilisateurs (sans :::).

# 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 — Importer des fonctions

#' @importFrom pkg fn1 fn2 importe des fonctions précises depuis un package dans votre espace de noms afin que vous puissiez les appeler sans le préfixe pkg::. Utilisez cette balise avec parcimonie : pkg::fn() explicite est plus clair et évite de polluer l’espace de noms.

# 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

Flux de travail avec devtools::document()

Après avoir modifié les commentaires roxygen2, appelez devtools::document() (Ctrl+Shift+D) pour régénérer man/*.Rd et mettre à jour NAMESPACE. Affichez ensuite la page d’aide avec ?add (après load_all()) pour vérifier qu’elle s’affiche correctement.

# 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

Documenter plusieurs fonctions sur une seule page

Utilisez #' @rdname shared_name pour regrouper plusieurs fonctions apparentées sur une seule page d’aide. La fonction principale reçoit le bloc roxygen2 complet ; les fonctions secondaires ne reçoivent que @rdname et @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

Autres balises utiles

Balises roxygen2 supplémentaires pour une documentation complète :

  • #' @seealso \code{\link{other_fn}} — renvoi croisé
  • #' @note — remarques supplémentaires après la description
  • #' @author Name — auteur de la fonction
  • #' @keywords internal — masque la fonction de l’index du package tout en conservant sa page d’aide
  • #' @family group_name — regroupe les fonctions apparentées dans l’aide
# #' 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

Vérification rapide : balise @export

Qu’advient-il d’une fonction d’un package R qui possède une documentation roxygen2, mais PAS de balise #' @export ?

Récapitulatif de la documentation roxygen2

Balises roxygen2 essentielles pour une documentation complète d’un package R :

  • #' @title / première ligne — titre de la fonction
  • #' @description — description détaillée
  • #' @param name Description — documenter chaque argument
  • #' @return Description — décrire la valeur renvoyée
  • #' @examples \n code — exemples exécutables (vérifiés par R CMD check)
  • #' @export — ajouter à NAMESPACE (rend la fonction publique)
  • #' @importFrom pkg fn — importer des fonctions précises
  • Exécuter devtools::document() pour régénérer man/ et NAMESPACE

Questions Fréquemment Posées

La leçon « Documenter des fonctions avec roxygen2 » est-elle gratuite ?

Oui — le texte complet de « Documenter des fonctions avec roxygen2 » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours R Academy, passe à CoddyKit PRO. Le cours R Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Documenter des fonctions avec roxygen2 » ?

Rédigez les balises @param, @return, @examples et @export pour générer automatiquement la documentation. Tu pratiques R Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer R Academy ?

Aucune expérience préalable n'est requise. R Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Documenter des fonctions avec roxygen2 » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon R Academy ?

Oui. Chaque leçon R Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Structure d’un paquet avec usethis et devtools
  2. Documenter des fonctions avec roxygen2
  3. Tests unitaires avec testthat
  4. Soumission à CRAN et maintenance des paquets
← Retour à R Academy