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 visualiser avec

  • L’aide à la fonction. Il s’agira d’une documentation plutôt courte.
?sd()

?dplyr::filter()

En plaçant votre curseur sur votre fonction, cliquez sur l’onglet Code puis “Insert Roxygen Skeleton”. Une squelette de documentation s’ajoute à votre fonction.

#' coefficient of variation (CV)
#'
#' @param x a vecteur of numbers
#'
#' @return
#' @export
#'
#' @examples
#' vec <- rnorm()
#' vec <- rnorm(mean = 10, sd = 5, n = 10)
#' cv(vec)
cv <- function(x) {
  (sd(x)/mean(x))*100
}
  • Une vignette. Une vignette est un document au format R Markdown qui va détailler tout le cheminement qui vous as mené à votre fonction finale. Toutes les fonctions ne disposent pas d’une vignette comme vous pouvez vous en doutez.
# 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