Documentación de los paquetes (Creación de paquetes en R 6ª parte)

La documentación de los paquetes es una tarea clave, ya que es la forma de explicar a los usuarios cómo utilizar las funciones y cual es la respuesta que se puede esperar. En un paquete de R la documentación de las funciones se incluye en los archivos Rd que se encuentra dentro de la carpeta man. Siendo esta la información que verán los usuarios cuando consulten la ayuda de las funciones. Para facilitar el mantenimiento de la documentación es una buena práctica escribir la documentación junto al código. Algo que se puede hacer con la ayuda del paquete roxygen2. Un paquete que trasforma los comentarios de las funciones función en formato de documentación estándar de R.

Esta entrada forma parte de la serie “Creación de paquetes en R” cuyo código se puede encontrar en el repositorio y consta de las siguientes ocho entradas:

Creación de paquetes en R
El archivo DESCRIPTION
Pruebas automáticas con testthat
Pruebas avanzadas con testthat
Medir la cobertura de las automáticas unitarias
Documentación de los paquetes
Creación de vignette
Validación y distribución de los paquetes

Instalación de `roxygen2`

Antes poder utilizar el paquete roxygen2 es necesario instalarlo, para lo que recurriremos como siempre al comando install.packages

install.packages("roxygen2")

Documentación de una función

Una vez instalado el paquete podemos comenzar a incluir la documentación del paquete. Para abriremos al archivo suma.R y, antes de la función suma(), podemos escribir comentarios que comiencen por #', lo que indica a roxygen2 que estos son los comentarios que debe procesar.
Además de esto existen comandos para indicar a roxygen2 información especial sobre la función como los parámetros de entrada, los datos de salida o ejemplos de código. Así los comandos más habituales son:

@param: después de este comando se escribe el nombre de un parámetro de entrada y una pequeña descripción de lo que la función espera en el mismo. Se tiene que crear una linea para cada uno de los parámetros de la función.
@return: con este comando se indica que incluye la respuesta de la función
@examples: a partir de este comando se puede incluir código R valido como a modo de ejemplo de uso.
@seealso: si la función está relacionada con otras aquí se indica esas otras funciones que el usuario puede consultar para tener más información.
@export: al escribir esta line se le indica a roxygen2 que agregue esta función al archivo NAMESPACE para que sea accesible para los usuarios. Lo más habitual es incluir esta opción en todas las funciones que se escriben en el paquete, ya que sino serán únicamente accesibles desde el interior del paquete.

Ejemplo de la función `suma()`

Por ejemplo, esta es la documentación que podemos incluir en para la función suma().

#' Suma dos números
#'
#' @param a un número
#' @param b un número
#'
#' @return La suma de \code{a} y \code{b}
#'
#' @examples
#' suma(1, 1)
#'
#' @export
suma <- function(a,b) {
  return(a + b)
}

Documentación del paquete

Además de para crear la documentación de las funciones también se puede usar roxygen2 para la de los paquetes. En este caso se escribirá la documentación como la de una función, pero en lugar de antes de una función se escribirá antes de una línea con la instrucción "_PACKAGE". Así la documentación de nuestro paquete puede ser simplemente:

#' Plantilla de Paquete R
#'
#' Esta es un paquete de ejemplo creado para el tutorial de Analytics Lane
#'
"_PACKAGE"

Creación de la documentación

Antes de crear la documentación es necesario borrar el archivo NAMESPACE que había creado el asistente de RStudio. Este archivo exporta todas las funciones del paquete y si no se elimina roxygen2 no lo sobrescribirá. Una vez eliminado este archivo solamente se tiene que escribir el comando devtools::document() para crear la documentación.

Conclusiones

En esta entrega hemos visto como con la ayuda del paquete roxygen2 documentar las funciones de R se vuelve extremadamente sencillo y fácil de mantener. Ya que podemos incluir la documentación en los comentarios para que el paquete se encargue de generar los archivos correspondientes. La semana que viene veremos cómo incluir tutoriales en nuestros paquete con la ayuda de R Markdown.

Imagen de Peter H en Pixabay