Escribir Documentación Roxygen

Crear documentación roxygen2 completa para funciones, conjuntos de datos y clases de paquetes R.

Cuándo Usar

• Añadir documentación a una nueva función exportada
• Documentar funciones auxiliares internas
• Documentar conjuntos de datos del paquete
• Documentar clases y métodos S3/S4/R6
• Corregir notas de

  R CMD check

  relacionadas con la documentación

Entradas

• Obligatorio: Función, conjunto de datos o clase R a documentar
• Opcional: Funciones relacionadas para referencias cruzadas (

  @family

  ,

  @seealso

  )
• Opcional: Si la función debe ser exportada

Procedimiento

Paso 1: Escribir la Documentación de la Función

Colocar los comentarios roxygen directamente encima de la función:

#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
  # implementation
}

Esperado: Bloque roxygen completo con título, descripción,

@param

@return

@examples

@export

En caso de fallo: Si se desconoce una etiqueta, consultar

?roxygen2::rd_roclet

@return

Paso 2: Referencia de Etiquetas Esenciales

#' Title

#' Description

@param

@return

@examples

@export

@family

@seealso

@keywords internal

Esperado: Se identifican todas las etiquetas obligatorias para el tipo de función. Las funciones exportadas tienen como mínimo

@param

@return

@examples

@export

En caso de fallo: Si una etiqueta es desconocida, consultar la documentación de roxygen2 para su uso y sintaxis.

Paso 3: Documentar Conjuntos de Datos

Crear

R/data.R

#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#'   \item{date}{Date of observation}
#'   \item{city}{City name}
#'   \item{temp_c}{Temperature in Celsius}
#'   \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"

Esperado:

R/data.R

@format

@source

En caso de fallo: Si

R CMD check

"city_temperatures"

usethis::use_data()

Paso 4: Documentar el Paquete

Crear

R/packagename-package.R

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

Esperado:

R/packagename-package.R

@keywords internal

"_PACKAGE"

devtools::document()

man/packagename-package.Rd

En caso de fallo: Si

R CMD check

R/<packagename>-package.R

"_PACKAGE"

Paso 5: Gestionar Casos Especiales

Funciones con puntos en el nombre (métodos S3):

#' @export
#' @rdname process
process.myclass <- function(x, ...) {
  # S3 method
}

Reutilizar documentación con

@inheritParams

#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
  # implementation
}

Corrección de "no visible binding" usando el pronombre

.data

#' @importFrom rlang .data
my_function <- function(df) {
  dplyr::filter(df, .data$column > 5)
}

Esperado: Los casos especiales (métodos S3, parámetros heredados, pronombre

.data

@rdname

@inheritParams

En caso de fallo: Si

R CMD check

#' @importFrom rlang .data

utils::globalVariables()

Paso 6: Generar la Documentación

devtools::document()

Esperado: El directorio

man/

.Rd

NAMESPACE

En caso de fallo: Revisar los errores de sintaxis de roxygen. Problemas frecuentes: corchetes sin cerrar en

\describe{}

#'

devtools::document()

Validación

• Cada función exportada tiene

  @param

  ,

  @return

  y

  @examples

• devtools::document()

  se ejecuta sin errores

• devtools::check()

  no muestra advertencias de documentación
• Las etiquetas

  @family

  agrupan correctamente las funciones relacionadas
• Los ejemplos se ejecutan sin errores (probar con

  devtools::run_examples()

  )

Errores Comunes

• Falta

  @return

  : CRAN requiere que todas las funciones exportadas documenten su valor de retorno
• Ejemplos que necesitan internet o autenticación: Envolver en

  \dontrun{}

  con un comentario explicativo
• Ejemplos lentos: Usar

  \donttest{}

  para ejemplos que funcionan pero tardan demasiado para CRAN
• Markdown en roxygen: Activar con

  Roxygen: list(markdown = TRUE)

  en DESCRIPTION
• Olvidar ejecutar

  devtools::document()

  : Las páginas man se generan, no se escriben a mano

Habilidades Relacionadas

• create-r-package

  - configuración inicial del paquete incluyendo roxygen

• write-testthat-tests

  - probar las funciones que se documentan

• write-vignette

  - documentación extensa más allá de la referencia de funciones

• submit-to-cran

  - requisitos de documentación para CRAN