¿Cómo documentar un package en R con roxygen2?

La documentación es uno de los aspectos más importantes en el desarrollo de un buen package. Sin él, los usuarios no sabrán cómo usarlo.

La documentación también es útil para el futuro: para ti (para que recuerdes qué deberían hacer tus funciones) y para los usuarios o desarrolladores que utilice tu package.

¿Cómo documentar un package en R?

Desarrollar una documentación para tu package es muy sencillo utilizando la librería roxygen2, que está inspirada en el sistema ‘Doxygen’ para C ++.

Al presionar Ctrl/Cmd + Shift + D (o ejecuta el comando devtools::document()) se generará un fichero man/add.Rd que se verá así:

% Generated by roxygen2 (4.0.0): do not edit by hand
\name{add}
\alias{add}
\title{Add together two numbers}
\usage{
add(x, y)
}
\arguments{
  \item{x}{A number}

  \item{y}{A number}
}
\value{
The sum of \code{x} and \code{y}
}
\description{
Add together two numbers
}
\examples{
add(1, 1)
add(10, 1)
}

Para más información, revisa esta la documentación oficial Escribir Documentación R en Markdown.

Proceso para generar la documentación

Para generar una documentación, hay que seguir cuatro pasos básicos:

  • Agrega comentarios roxygen a sus archivos .R.
  • Ejecuta el comando devtools::document() (o presione Ctrl / Cmd + Shift + D en RStudio) para convertir los comentarios de roxygen en archivos .Rd. (devtools::document() llama a roxygen2::roxygenise() para hacer el trabajo duro).
  • Realiza una vista previa de la documentación con el caracter ?.
  • Repite este proceso hasta que la documentación se vea como deseas.

Documentando funciones

Las funciones son el objeto más comúnmente documentado, la mayoría de las funciones tienen tres etiquetas: @param, @examples y @return.

  • @param name description describe las entradas o parámetros de la función. La descripción debe proporcionar un resumen sucinto del tipo del parámetro (por ejemplo, cadena, vector numérico) y, si no es obvio por el nombre, lo que hace el parámetro.
  • @examples proporciona código R ejecutable que muestra cómo usar la función en la práctica. Esta es una parte muy importante de la documentación porque muchas personas miran primero los ejemplos. El código de ejemplo debe funcionar sin errores ya que se ejecuta automáticamente como parte de la verificación R CMD.
  • @return description describe el resultado de la función. Esto no siempre es necesario, pero es una buena idea si su función devuelve diferentes tipos de salida dependiendo de la entrada, o si está devolviendo un objeto S3, S4 o RC.

roxygen2_get_operation_code

Puedes encontrar más información de cómo documentar un package en R en el libro R packages by Hadley Wickham.

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

w

Conectando a %s