Documentando funções com roxygen2
Escreva tags @param, @return, @examples e @export para gerar documentação automaticamente.
Documentando funções com roxygen2 é uma aula grátis de R Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de R Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de R Academy inclui 4 aulas no total.
O que é roxygen2?
roxygen2 permite escrever a documentação do R diretamente acima da função, como comentários especialmente formatados que começam com #'. Quando você executa devtools::document(), o roxygen2 interpreta esses comentários, gera arquivos man/*.Rd e atualiza NAMESPACE automaticamente.
O bloco mínimo do roxygen2
O bloco de documentação mais simples precisa de pelo menos um título e uma descrição. A primeira frase (até o primeiro ponto ou linha em branco) se torna o título. Os parágrafos seguintes se tornam a descrição.
# 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
# }Tags @title e @description
Use as tags explícitas @title e @description quando a convenção do primeiro parágrafo não for suficiente — por exemplo, quando o título precisar ser diferente do nome da função ou quando a descrição tiver vários parágrafos.
# #' @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 — Documentando argumentos
#' @param name Description documenta um argumento da função. Use uma linha @param para cada argumento. A descrição deve informar o tipo esperado e o que o argumento controla.
# #' 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 — Documentando o valor retornado
#' @return Description descreve o que a função retorna. Informe o tipo, a classe e a estrutura do valor retornado. Isso é obrigatório para o envio ao 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 — Exemplos de código executáveis
#' @examples fornece código que aparece na página de ajuda e é executado por R CMD check. Os exemplos devem ser concluídos em menos de 5 segundos e não podem exigir recursos externos (rede, arquivos). Cada linha é código R comum — não são necessários prefixos especiais.
# #' 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 — Tornando funções públicas
#' @export instrui o roxygen2 a adicionar a função a NAMESPACE, tornando-a disponível para os usuários do seu pacote. As funções sem @export são internas — podem ser chamadas dentro do pacote, mas não pelos usuários (sem :::).
# 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 — Importando funções
#' @importFrom pkg fn1 fn2 importa funções específicas de um pacote para o seu espaço de nomes, permitindo chamá-las sem o prefixo pkg::. Use essa opção com moderação — pkg::fn() explícito é mais claro e evita a poluição do espaço de nomes.
# 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 minimalFluxo de trabalho de devtools::document()
Depois de editar os comentários do roxygen2, chame devtools::document() (Ctrl+Shift+D) para regenerar man/*.Rd e atualizar NAMESPACE. Em seguida, visualize a página de ajuda com ?add (após load_all()) para confirmar que ela está correta.
# 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 errorsDocumentando várias funções em uma página
Use #' @rdname shared_name para reunir várias funções relacionadas em uma única página de ajuda. A função principal recebe o bloco completo do roxygen2; as funções secundárias recebem apenas @rdname e @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 - yOutras tags úteis
Tags adicionais do roxygen2 para uma documentação completa:
#' @seealso \code{\link{other_fn}}— referência cruzada#' @note— observações adicionais após a descrição#' @author Name— autor da função#' @keywords internal— oculta do índice do pacote, mas mantém a página de ajuda#' @family group_name— agrupa funções relacionadas na ajuda
# #' 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 + yVerificação rápida: tag @export
O que acontece com uma função de um pacote R que tem documentação do roxygen2, mas NÃO tem a tag #' @export?
Recapitulação da documentação com roxygen2
Principais tags do roxygen2 para uma documentação completa de pacotes R:
#' @title/ primeira linha — título da função#' @description— descrição detalhada#' @param name Description— documentar cada argumento#' @return Description— descrever o valor retornado#' @examples \n code— exemplos executáveis (verificados por R CMD check)#' @export— adicionar a NAMESPACE (torna a função pública)#' @importFrom pkg fn— importar funções específicas- Execute
devtools::document()para regenerar man/ e NAMESPACE
Perguntas Frequentes
A aula “Documentando funções com roxygen2” é grátis?
Sim — o texto completo de “Documentando funções com roxygen2” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de R Academy, atualize para CoddyKit PRO. O curso de R Academy inclui 4 aulas no total.
O que vou aprender em “Documentando funções com roxygen2”?
Escreva tags @param, @return, @examples e @export para gerar documentação automaticamente. Você pratica R Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar R Academy?
Nenhuma experiência prévia é necessária. R Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Documentando funções com roxygen2”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de R Academy?
Sim. Cada aula de R Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Estrutura de pacotes com usethis e devtools
- Documentando funções com roxygen2
- Testes unitários com testthat
- Submissão ao CRAN e manutenção de pacotes