Documenter les fonctions

TP

Auteur·rice·s
Affiliation

Ghislain Durif

Frédéric Santos

CNRS, Univ. Bordeaux, MCC – UMR 5199 PACEA

1 Les fichiers .Rd

La documentation d’une fonction permet à l’utilisateur d’obtenir des informations (techniques) utiles lorsqu’il appelle la fonction help(). Par exemple, pour consulter la fonction lda() du package {MASS} :

help(MASS::lda)

Tout ce qui figure dans cette page d’aide est mis en forme automatiquement à partir du contenu du fichier .Rd associé, contenu dans le dossier man/ du package.

Exercice. Étudier le contenu du fichier lda.Rd du package {MASS}, en ayant en parallèle sous les yeux la page d’aide rendue par Rstudio.

Historiquement, ces fichiers étaient directement saisis à la main par les auteurs de packages R. Certains éditeurs de code (par exemple Emacs) ont d’ailleurs de bons modes d’édition de fichiers .Rd, et facilitent considérablement cette tâche. Cette démarche reste à l’heure actuelle parfaitement valable. Par exemple, documenter la fonction ccc() de notre package peut consister à créer un fichier ccc.Rd à la main1, et à l’enregistrer dans le dossier man/.

Toutefois, certains auteurs de package trouvent cette approche inconfortable, car elle sépare en deux fichiers différents le code (.R) et la documentation (.Rd) de la fonction. On peut souhaiter préférer écrire la documentation et le code dans le même fichier afin d’éviter des aller-retours : c’est ce que permet le package {roxygen2}.

2 Le package {roxygen2}

Le package {roxygen} permet :

  • de saisir la documentation de chaque fonction R d’un package directement dans son fichier .R, sous forme de lignes de commentaires (préfixés avec #' afin d’être reconnaissables) situées juste au-dessus du corps de la fonction ;
  • de créer automatiquement le fichier .Rd associé à chaque fonction en faisant appel à la fonction document().

La génération automatique de fichiers .Rd évite aussi de commettre des erreurs de syntaxe sur ces fichiers assez sensibles, comme cela pourrait arriver en les écrivant à la main.

Concrètement, voici un extrait de documentation écrite avec la syntaxe Roxygen, directement dans le code R de la fonction fviz_ca() du package {factoextra}. Après avoir exécuté la fonction document(), l’auteur du package a alors pu générer automatiquement le fichier fviz_ca.Rd correspondant.

3 En pratique : documenter la fonction ccc()

Exercice. Écrivons et produisons à présent la documentation de la fonction ccc().

  1. Revenir sur le fichier ccc.R, et placer le curseur à n’importe quel endroit du code de la fonction ccc().
  2. Dans le menu Code de Rstudio, choisir “Insert Roxygen Skeleton”.
  3. Compléter, de manière assez intuitive, les différents champs title, param, etc. Inclure également un court exemple de fonctionnement dans la section examples.
  4. Dans la console R, exécuter l’instruction document() pour générer le fichier ccc.Rd correspondant. Le consulter.
  5. Taper help(ccc) dans la console R pour vérifier que la documentation a correctement été générée.
  6. Faire un commit après ces opérations, avec un message explicite.
Retour au sommet

Notes de bas de page

  1. On pourrait obtenir un template pré-rempli pour la documentation de cette fonction en exécutant prompt(ccc, force.function = TRUE) dans la console R : le fichier .Rd devrait alors être complété à la main puis déplacé dans le dossier man/.↩︎