4. Documentar funciones

⏱ Enseñanza: 7 minutos · Ejercicios: 10 minutos

Preguntas

  • ¿Cómo hago para que mi función tenga una página de ayuda?
  • ¿Qué quiere decir que una función se “exporta”?

Objetivos

  • Escribir comentarios de roxygen2 para una función.
  • Generar la documentación con devtools::document().
  • Explicar qué hace la etiqueta @export.

¿Por qué documentar?

El código lo lee la computadora. La documentación la leen las personas: vos dentro de ocho meses, tu equipo, alguien que encontró tu paquete.

En R, la documentación de una función es lo que aparece cuando escribimos ? funcion o presionamos F1 arriba del nombre de la función. Esas páginas se guardan en archivos .Rd en la carpeta man/, con un formato específico. Por esa razón, no los vamos a escribir a mano: roxygen2 los genera a partir de comentarios especiales, que escribimos justo arriba de la función.

El esqueleto de roxygen2

💻 En vivo

Con el cursor adentro de la función, seleccionamos el menú: Code > Insert Roxygen Skeleton (o Ctrl + Alt + Shift + R).

En Positron: hacé clic en la bombilla 💡 que aparece cerca del nombre de la función y elegí Generate a roxygen template.

#' Title
#'
#' @return
#' @export
#'
#' @examples
dicho_al_azar <- function() {

Cada línea empieza con #' (numeral y apóstrofo). Las etiquetas empiezan con @.

Completar la documentación

💻 En vivo, en R/dicho_al_azar.R

#' Elegir un dicho al azar
#'
#' Devuelve un dicho popular de América Latina elegido al azar.
#'
#' @return Un texto (vector de caracteres) con el dicho.
#' @export
#'
#' @examples
#' dicho_al_azar()
dicho_al_azar <- function() {
  dichos <- c(
    "Estoy al horno",
    "Como perro en cancha de bochas",
    "Pasarlo chancho"
  )
  sample(dichos, size = 1)
}
  • La primera línea es el título. Corto, sin punto final.
  • El párrafo siguiente es la descripción. Qué hace la función.
  • @param documenta cada argumento. Esta función todavía no tiene, pero se lo vamos a agregar en el episodio de datos.
  • @return dice qué devuelve la función: qué tipo de objeto, de qué largo, qué columnas.
  • @examples tiene código que muestra cómo se usa. Tiene que funcionar porque check() lo corre.
  • @export hace que la función esté disponible para quien instale el paquete.

Generar la documentación

💻 En vivo

devtools::document()
#> ℹ Updating dichosos documentation
#> ℹ Loading dichosos
#> Writing NAMESPACE
#> Writing dicho_al_azar.Rd

?dicho_al_azar

Atajo de teclado: Ctrl + Shift + D (en Mac, Cmd + Shift + D).

document() hizo dos cosas:

  1. Escribió man/dicho_al_azar.Rd, la página de ayuda.
  2. Agregó export(dicho_al_azar) en NAMESPACE.

Funciones exportadas e internas

No todas las funciones de un paquete tienen que estar disponibles para las personas que lo usan. A veces escribimos funciones auxiliares, que solo usan otras funciones del paquete.

  • Con @export: la función es pública. Se puede usar después de library(dichosos).
  • Sin @export: la función es interna. Solo la usan otras funciones del paquete (o vos, con dichosos:::funcion()).
Notaload_all() es generosa

Con load_all() podés usar todas las funciones, exportadas o no. Por eso a veces no nos damos cuenta de que olvidamos un @export hasta que instalamos el paquete.

TipMarkdown en la documentación

usethis activa Markdown en roxygen2 (fijate la línea Roxygen: list(markdown = TRUE) en DESCRIPTION). Podés usar **negrita**, `código` y enlaces a otras funciones como [dicho_del_dia()].

Desafío 4.1: Documentá dicho_al_azar() 8 minutos

  1. Poné el cursor adentro de la función e insertá el esqueleto de roxygen2 (Code > Insert Roxygen Skeleton).
  2. Completá el título, la descripción, @return y @examples.
  3. Corré devtools::document() y mirá la ayuda con ?dicho_al_azar.
  4. Abrí el archivo NAMESPACE. ¿Qué cambió?
#' Elegir un dicho al azar
#'
#' Devuelve un dicho popular de América Latina elegido al azar.
#'
#' @return Un texto (vector de caracteres) con el dicho.
#' @export
#'
#' @examples
#' dicho_al_azar()
dicho_al_azar <- function() {
  # ...
}
devtools::document()
?dicho_al_azar

NAMESPACE ahora tiene la línea export(dicho_al_azar), gracias a la etiqueta @export.

Desafío 4.2: Encontrá los errores 5 minutos, en parejas

Esta documentación tiene tres errores. ¿Cuáles son?

#' Elegir un dicho al azar
#
#' Devuelve un dicho popular elegido al azar.
#'
#' @params pais El país del que queremos el dicho.
#' @return Un texto con el dicho.
#'
#' @examples
#' dicho_al_azar()
dicho_al_azar <- function(pais = NULL) {
  # ...
}
  1. La segunda línea empieza con # en lugar de #'. Para roxygen2, ahí termina el bloque.
  2. La etiqueta es @param, en singular, no @params.
  3. Falta @export. Sin esa etiqueta, la función no se exporta: no se puede usar con library(dichosos) después de instalar el paquete.

Desafío 4.3 (si te sobra tiempo o para hacerlo en casa): La ayuda por dentro 2 minutos

Abrí la carpeta man/ y el archivo dicho_al_azar.Rd. ¿Lo escribiste vos? ¿Lo deberías editar?

Lo escribió roxygen2, a partir de tus comentarios. La primera línea dice % Generated by roxygen2: do not edit by hand. Si lo editás a mano, la próxima vez que corras document() se pierden los cambios. Siempre se edita el comentario #' en el archivo .R.

Puntos clave

  • La documentación se escribe con comentarios #' arriba de cada función.
  • devtools::document() genera las páginas de ayuda en man/ y actualiza NAMESPACE.
  • @export hace que una función sea pública.
  • Nunca edites a mano NAMESPACE ni los archivos de man/.