9.2 Documenter sa fonction

La documentation d’une fonction est une étape souvent négligée. Cependant, une fonction bien documentée est une fonction qui sera employée à l’avenir. Les fonctions mal documentées sont des fonctions qui seront généralement peu employées, souvent mal employées et enfin oubliées. Lorsque l’on souhaite écrire une fonction, il convient de la documenter directement. La documentation se fait par le biais de deux outils principalement que vous pouvez inclure dans un package (voir module 12) : la page d’aide de la fonction et une “vignette”.

La page d’aide des fonctions R est généralement assez courte et très technique. Une section exemples éventuelle vous montre comment utiliser la fonction en pratique. Examiner les pages d’aide des deux fonctions suivantes que vous activez à l’aide de l’instruction ?<fonction> pour vous en faire une idée.

?sd
?dplyr::filter

Pour rédiger l’information nécessaire à l’élaboration de la page d’aide de votre fonction, vous pouvez vous aider d’un “template” calculé par RStudio. Placez votre curseur à l’intérieur de votre fonction dans le fichier script R. Sélectionnez l’entrée de menu Code -> Insert Roxygen Skeleton. Un squelette de documentation s’ajoute à votre fonction. Il est rédigé dans un format qui s’appelle Roxygen. Voici

#' coefficient of variation (CV)
#'
#' @param x a numeric vecteur
#' @param na.rm shouls missing values be eliminated from the calculation? `FALSE` by default.
#'
#' @return
#' A single value is returned with the standard deviation dived by the mean times 100.
#' 
#' @export
#'
#' @examples
#' vec <- rnorm(10, mean = 3, sd = 5)
#' cv(vec)
cv <- function(x, na.rm = FALSE) {
  sd(x, na.rm = na.rm) / mean(x, na.rm = na.rm) * 100
}

Examinez l’exemple ci-dessus. Vous avez écrit une fonction cv(). Tout le commentaire au-dessus est le contenu Roxygen qui documente votre fonction. Chaque ligne commence par #'. La première ligne est un titre, les autres sont des champs particuliers qui seront interprétés par le convertisseur en page d’aide. Par exemple pour documenter un argument de votre fonction, vous utilisez @param <arg> <description> avec l’étiquette @param. Pareil pour @return (ce que la fonction renvoie), ou @examples, un ou plusieurs exemples d’utilisation. Notez que la description peut s’étaler sur plusieurs lignes suivant l’étiquette, comme pour @examples. L’étiquette @export indique pour un package que la fonction sera “exportée”, c’est-à-dire, visible par l’utilisateur final du package (il peut aussi y avoir des fonctions internes au package uniquement). Pour apprendre à utiliser Roxygen dans sa dernière version (la deux), voyez le site du package roxygen2. Vous avez aussi accès à un aide-mémoire rapide dans Rstudio via le menu Help -> Roxygen Quick Reference.

Une autre façon de documenter une fonction consiste à écrire une vignette. Il s’agit d’un document au format R Markdown qui va détailler l’utilisation concrète de la fonction dans le contexte d’un petit tutoriel. Les vignettes servent aussi à expliquer le pourquoi et le comment d’une fonction. Toutes les fonctions ne disposent pas d’une vignette comme vous pouvez vous en douter.

# Pour prendre connaissance des vignettes disponible dans un package
vignette(package = 'dplyr')
# Visualiser une vignette particulière
vignette("dplyr", package = 'dplyr')

Pour en savoir plus