Documentar packages amb Roxygen2

Seguint la presentació de Crear packeges de forma fàcil amb RStudio, considero interessant utilitzar el package Roxygen2 per generar la documentació del package. Per entendre millor el video tutorial al final de l’entrada, afegeixo les explicacions teòriques en què consisteix i com utilitzar el package Roxygen2.

Perquè és interessant roxygen2?

La documentació és un dels aspectes més importants del desenvolupament del package. Sense ella, els usuaris no saben com utilitzar-lo, i és poc probable que el facin servir. La documentació també és útil per saber què s’estava pensant quan es va programar la funció, tant per qui la va fer, com pels altres desenvolupadors del package.

La forma estàndard d’escriure la documentació de R és crear arxius .Rd al directory man/. Aquests fitxers descriuen cada objecte (funció, conjunt de dades, la classe o mètode genèric) en el seu package, documentant com funciona i donant exemples de com fer-lo servir. Els arxius .Rd són un format de fitxer especial vagament basats en làtex. Podeu llegir més sobre el format dels arxius a Writing R extensions.

En lloc d’escriure a mà els arxius .Rd, utilitzarem el package roxygen2. Amb roxygen, s’escriu la documentació en els comentaris al costat de cada funció, i després s’executa una funció del package per crear els arxius principals.

Aquest flux de treball té una sèrie d’avantatges respecte escriure la documentació dels arxius .Rd a mà:

  • El codi i la documentació estan junts de manera que quan es modifica el codi, és més fàcil d’enrecordar-se d’actualitzar la documentació.
  • Evita deixar tota la documentació per fer al final. Evitant així acumular molt treball de documentació de moltes funcions i data sets, resultant habitualment en una documentació deficient per anar depresa o no poder-hi dedicar tant de temps seguit.
  • Roxygen2 inspecciona dinàmicament tots els objectes que es documenten, per la qual cosa permet incloure informació interrelacionada entre els diferents objectes. Funcions d’una mateixa família, objectes que enllacen altres que poden ser d’interès.
  • Roxygen2 s’encarrega d’actualitzar automàticament arxius que són incòmodes de mantenir a mà, com el NAMESPACE, el camp Collate al DESCRIPTION, i l’índex de les demos.

Documentar amb Roxygen2

Els comentaris roxygen tenen un format especial. Comencen amb #' i inclouen variables de la forma @tag que trenquen la documentació en trossos. El contingut d’una etiqueta s’estén des del nom d’etiqueta fins l’etiqueta següent, i poden abastar diverses línies.

Cada bloc de documentació comença amb una descripció de text. La primera línia es converteix en el títol de la documentació. Això és el que veus quan mires a help(package = mypackage) i es mostra a la part superior de la documentació de cada package. Ha de ser concís. El segon apartat és la descripció: això és el primer que apareix en la documentació i ha de descriure breument el que fa la funció. Els paràgrafs tercer i posteriors son els detalls: es tracta d’una secció que ve després de la descripció dels paràmetres. Per anul·lar el comportament predeterminat es pot utilitzar @title@description i @details.

Els tags més comuns que fem servir són els següents:

  • @name nom de la funció
  • @title títol de la funció
  • @param nom i explicació de les variables
  • @author autor de la funció
  • @note aclariments o informació complementaria de la funció
  • @export indica si una funció es visible afegint-la al NAMESPACE
  • @import indica quines funcions o packages s’han d’incloure al NAMESPACE
  • @examples exemples del funcionament de la funció
  • @return explicació del resultat de la funció

Funcionament Roxygen2

Una cop documentats tots els objectes del package, per convertir els comentaris roxygen a arxius .Rd, es pot executar la funció roxygenize del package però nosaltres farem servir l’RStudio clickant la pestanya pertinent o definint que cada cop que fem el package ens documenti les funcions. Al videotutorial es veu com es fa.

Això genera o actualitza els arxius .Rd i els guarda al directori man/.

Documentar automàticament el NAMESPACE

Al documentar una funció, la primera decisió que s’ha de prendre és si es vol exportar o no. Les exportacions es descriuen al NAMESPACE i indica que es pot utilitzar al carregar el package. Totes les funcions que vulguem exportar han de ser documentades amb el tag @export. No cal documentar les funcions internes, però pot ser una bona pràctica si és particularment complicada.

Si el nostre package utilitza altres packages o funcions s’ha d’afegir a la documentació amb el tag @import.

Referències

La informació del package Roxygen2 està bastant dispersa però els següents enllaços poden ajudar a entendre una mica millor el seu funcionament. També afegeixo enllaços de com documentar packages.

Videotutorial

Tags: , , ,

4 responses to “Documentar packages amb Roxygen2”

  1. Xavier de Pedro says :

    Gràcies Lluís! Algun día m’hi he de posar amb els scripts que ja tinc creats per a convertir-los en paquets… i Roxygen2 sembla un bon candidat a ajudar-me amb la tasca. I sobretot per que un cop après, els nous scripts/paquets s’aniran documentant de forma més fàcil a mesura que els escrigui i depuri les funcions, etc.🙂

    Xavi

    • rugbcn says :

      Hola Xavi,

      Si tens bastanta cosa val la pena i la veritat és que és molt fàcil. Recomano sincerament que utilitzis RStudio i roxygen perquè simplifica molt el procés.

      Una abraçada,

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: