0Pricing
R Academy · Lección

Documentación de funciones con roxygen2

Escriba las etiquetas @param, @return, @examples y @export para generar documentación automáticamente.

Documentación de funciones con roxygen2 es una lección gratuita de R Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de R Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de R Academy incluye 4 lecciones en total.

¿Qué es roxygen2?

roxygen2 permite escribir la documentación de R directamente encima de la función, como comentarios con un formato especial que comienzan por #'. Al ejecutar devtools::document(), roxygen2 analiza estos comentarios, genera los archivos man/*.Rd y actualiza NAMESPACE automáticamente.

El bloque mínimo de roxygen2

El bloque de documentación más sencillo necesita al menos un título y una descripción. La primera oración (hasta el primer punto o la primera línea en blanco) se convierte en el título. Los párrafos posteriores se convierten en la descripción.

# R/add.R
#
# #' Add two numbers
# #'
# #' Computes the sum of x and y. Both arguments must be numeric.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

Etiquetas @title y @description

Utilice las etiquetas explícitas @title y @description cuando la convención del primer párrafo no sea suficiente; por ejemplo, cuando el título deba diferir del nombre de la función o cuando la descripción tenga varios párrafos.

# #' @title Safe Addition of Numeric Values
# #' @description
# #' Adds two numeric vectors element-wise.
# #' Returns NA where either input is NA.
# #' Useful for financial calculations where NA propagation matters.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@param — Documentar los argumentos

#' @param name Description documenta un argumento de la función. Utilice una línea @param por cada argumento. La descripción debe indicar el tipo esperado y qué controla el argumento.

# #' Add two numbers
# #'
# #' @param x A numeric vector. The first operand.
# #' @param y A numeric vector. The second operand. Must be the same length as x
# #'   or length 1 (recycled).
# #'
# #' @export
# add <- function(x, y) {
#   if (!is.numeric(x) || !is.numeric(y)) stop('x and y must be numeric')
#   x + y
# }

@return — Documentar el valor devuelto

#' @return Description describe lo que devuelve la función. Indique el tipo, la clase y la estructura del valor devuelto. Esto es obligatorio para enviar el paquete a CRAN.

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of the same length as the longer of x or y,
# #'   containing the element-wise sums.
# #'
# #' @export
# add <- function(x, y) x + y

@examples — Ejemplos de código ejecutables

#' @examples proporciona código que aparece en la página de ayuda y que ejecuta R CMD check. Los ejemplos deben completarse en menos de 5 segundos y no deben requerir recursos externos (red o archivos). Cada línea es código R normal; no se necesitan prefijos especiales.

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of element-wise sums.
# #' @examples
# #' add(1, 2)
# #' add(c(1, 2, 3), c(10, 20, 30))
# #' add(0, -5)
# #' @export
# add <- function(x, y) x + y

@export — Hacer públicas las funciones

#' @export indica a roxygen2 que añada la función a NAMESPACE, de modo que esté disponible para los usuarios del paquete. Las funciones sin @export son internas: se pueden llamar dentro del paquete, pero no los usuarios (sin utilizar :::).

# Public function — exported:
# #' @export
# add <- function(x, y) x + y
#
# Internal helper — not exported:
# check_numeric <- function(x) {
#   if (!is.numeric(x)) stop('Expected numeric')
# }
#
# After devtools::document(), NAMESPACE will contain:
# export(add)
# but NOT check_numeric

@importFrom — Importar funciones

#' @importFrom pkg fn1 fn2 importa funciones específicas de un paquete a su espacio de nombres para que pueda llamarlas sin el prefijo pkg::. Utilícelo con moderación; pkg::fn() explícito es más claro y evita contaminar el espacio de nombres.

# Option 1 — @importFrom (adds to NAMESPACE, no pkg:: needed):
# #' @importFrom stringr str_trim str_to_lower
# clean <- function(x) str_to_lower(str_trim(x))
#
# Option 2 — explicit :: (recommended for clarity):
# clean <- function(x) {
#   stringr::str_to_lower(stringr::str_trim(x))
# }
#
# Both work; prefer Option 2 to keep NAMESPACE minimal

Flujo de trabajo de devtools::document()

Después de editar los comentarios de roxygen2, llame a devtools::document() (Ctrl+Shift+D) para volver a generar man/*.Rd y actualizar NAMESPACE. Después, consulte la página de ayuda con ?add (tras ejecutar load_all()) para confirmar que tiene el aspecto correcto.

# Full documentation cycle:
# 1. Edit roxygen2 comments in R/add.R
# 2. devtools::document()     # regenerate man/ and NAMESPACE
# 3. devtools::load_all()     # reload package
# 4. ?add                     # preview the help page
# 5. devtools::check()        # ensure no documentation errors

Documentar varias funciones en una sola página

Utilice #' @rdname shared_name para combinar varias funciones relacionadas en una sola página de ayuda. La función principal recibe el bloque completo de roxygen2; las funciones secundarias solo reciben @rdname y @export.

# R/arithmetic.R
#
# #' Basic Arithmetic
# #' @param x,y Numeric vectors.
# #' @return A numeric vector.
# #' @examples
# #' add(1, 2); subtract(5, 3)
# #' @export
# add <- function(x, y) x + y
#
# #' @rdname add
# #' @export
# subtract <- function(x, y) x - y

Otras etiquetas útiles

Etiquetas adicionales de roxygen2 para completar la documentación:

  • #' @seealso \code{\link{other_fn}} — referencia cruzada
  • #' @note — notas adicionales después de la descripción
  • #' @author Name — autor de la función
  • #' @keywords internal — oculta la función del índice del paquete, pero conserva su página de ayuda
  • #' @family group_name — agrupa funciones relacionadas en la ayuda
# #' Add two numbers
# #' @param x,y Numeric vectors.
# #' @return Numeric vector.
# #' @seealso \code{\link{subtract}} for the inverse operation.
# #' @family arithmetic
# #' @examples
# #' add(1, 1)
# #' @export
# add <- function(x, y) x + y

Comprobación rápida: etiqueta @export

¿Qué ocurre con una función de un paquete de R que tiene documentación de roxygen2, pero NO tiene la etiqueta #' @export?

Repaso de la documentación con roxygen2

Etiquetas principales de roxygen2 para documentar completamente un paquete de R:

  • #' @title / primera línea — título de la función
  • #' @description — descripción detallada
  • #' @param name Description — documentar cada argumento
  • #' @return Description — describir el valor devuelto
  • #' @examples \n code — ejemplos ejecutables (comprobados por R CMD check)
  • #' @export — añadir al NAMESPACE (hace pública la función)
  • #' @importFrom pkg fn — importar funciones específicas
  • Ejecute devtools::document() para volver a generar man/ y NAMESPACE

Preguntas frecuentes

¿La lección «Documentación de funciones con roxygen2» es gratis?

Sí — el texto completo de «Documentación de funciones con roxygen2» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de R Academy, actualiza a CoddyKit PRO. El curso de R Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Documentación de funciones con roxygen2»?

Escriba las etiquetas @param, @return, @examples y @export para generar documentación automáticamente. Practicas R Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar R Academy?

No se requiere experiencia previa. R Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Documentación de funciones con roxygen2»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de R Academy?

Sí. Cada lección de R Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Estructura de paquetes con usethis y devtools
  2. Documentación de funciones con roxygen2
  3. Pruebas unitarias con testthat
  4. Envío a CRAN y mantenimiento de paquetes
← Volver a R Academy