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 aroxygen2
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.
Deja una respuesta