R Language
Roxygen2

Paramètres

Documenter un paquet avec roxygen2

Ecrire avec roxygen2

roxygen2 est un package créé par Hadley Wickham pour faciliter la documentation.

Il permet d'inclure la documentation dans le script R, dans les lignes commençant par #' . Les différents paramètres transmis à la documentation commencent par un @ , par exemple le créateur d'un paquet écrit comme suit:

#' @author The Author

Par exemple, si nous voulions documenter la fonction suivante:

mean<-function(x) sum(x)/length(x)

Nous voudrons écrire une petite description de cette fonction et expliquer les paramètres avec ce qui suit (chaque ligne sera expliquée et détaillée après):

#' Mean
#'
#' A function to compute the mean of a vector
#' @param x A numeric vector
#' @keyword mean
#' @importFrom base sum
#' @export
#' @examples
#' mean(1:3)
#' \dontrun{ mean(1:1e99) }
mean<-function(x) sum(x)/length(x)

• La première ligne #' Mean est le titre de la documentation, les lignes suivantes constituent le corpus.
• Chaque paramètre d'une fonction doit être détaillé via un @param pertinent. @export indiqué que ce nom de fonction doit être exporté et peut donc être appelé lorsque le paquet est chargé.
• @keyword fournit des mots-clés pertinents lors de la recherche d'aide
• @importFrom répertorie toutes les fonctions à importer à partir d'un package qui sera utilisé dans cette fonction ou dans votre package. Notez que l'importation de l'espace de noms complet d'un package peut être effectuée avec @import
• Les exemples sont ensuite écrits sous la balise @example .
  • Le premier sera évalué lors de la construction du package;
  • Le second ne sera pas - généralement pour éviter de longs calculs - dû à la commande \dontrun .

Construire la documentation

La documentation peut être créée en utilisant devtools::document() . Notez également que devtools::check() créera automatiquement une documentation et signalera les arguments manquants dans la documentation des fonctions en tant qu'avertissements.