help(MASS::lda)
Documenter les fonctions
TP
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}
:
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 fonctiondocument()
.
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()
.
- Revenir sur le fichier
ccc.R
, et placer le curseur à n’importe quel endroit du code de la fonctionccc()
. - Dans le menu Code de Rstudio, choisir “Insert Roxygen Skeleton”.
- Compléter, de manière assez intuitive, les différents champs
title
,param
, etc. Inclure également un court exemple de fonctionnement dans la sectionexamples
. - Dans la console R, exécuter l’instruction
document()
pour générer le fichierccc.Rd
correspondant. Le consulter. - Taper
help(ccc)
dans la console R pour vérifier que la documentation a correctement été générée. - Faire un commit après ces opérations, avec un message explicite.
Notes de bas de page
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 dossierman/
.↩︎