roxygen2

roxygène2

Le principe de roxygen2 est simple : décrivez vos fonctions dans des commentaires à côté de leurs définitions et roxygen2 traitera votre code source et vos commentaires pour générer automatiquement les fichiers .Rd dans man/ , NAMESPACE et, si nécessaire, le champ Collate dans DESCRIPTION .

Installation

 # Install roxygen2 from CRAN
install.packages( " roxygen2 " )

# Or the development version from GitHub:
# install.packages("pak")
pak :: pak( " r-lib/roxygen2 " )

Usage

Le principe de roxygen2 est simple : décrivez vos fonctions dans des commentaires à côté de leurs définitions et roxygen2 traitera votre code source et vos commentaires pour produire des fichiers Rd dans le répertoire man/ . Voici un exemple simple tiré du package stringr :

 # ' The length of a string
# '
# ' Technically this returns the number of "code points", in a string. One
# ' code point usually corresponds to one character, but not always. For example,
# ' an u with a umlaut might be represented as a single character or as the
# ' combination a u and an umlaut.
# '
# ' @inheritParams str_detect
# ' @return A numeric vector giving number of characters (code points) in each
# '    element of the character vector. Missing string have missing length.
# ' @seealso [stringi::stri_length()] which this function wraps.
# ' @export
# ' @examples
# ' str_length(letters)
# ' str_length(NA)
# ' str_length(factor("abc"))
# ' str_length(c("i", "like", "programming", NA))
str_length <- function ( string ) {
}

Lorsque vous roxygenise() (ou devtools::document() ) votre package, ces commentaires seront automatiquement transformés en .Rd que R utilise pour générer la documentation que vous voyez lorsque vous tapez ?str_length .

Apprendre encore plus

Pour commencer, lisez d’abord vignette("roxygen2") . Ensuite, lisez-en davantage sur le composant de package spécifique que vous souhaitez générer :

• Commencez par vignette("rd") pour savoir comment documenter vos fonctions avec roxygen2.

• vignette("rd-other") explique comment documenter d'autres éléments tels que les ensembles de données, le package lui-même et les différents éléments utilisés par les systèmes POO de R.

• vignette("rd-formatting") donne les détails de la prise en charge de rmarkdown par roxygen2.

• vignette("reuse") montre les outils disponibles pour réutiliser la documentation à plusieurs endroits.

• vignette("namespace") décrit comment générer un fichier NAMESPACE , comment fonctionne l'espace de noms dans R et comment vous pouvez utiliser roxygen2 pour être précis sur les besoins et les fournitures de votre package.

• Pour le champ Collate dans DESCRIPTION , voir ?update_collate() .