Pacotes (Zen do R parte 6)

Documentação

Para poder programar pacotes com mais facilidade, é necessário instalar o devtools. Assim como o tidyverse, este é um conjunto de pacotes (que inclui o usethis por sinal) que auxiliam no processo de criar e testar um pacote de R.

install.packages("devtools")

A partir de agora você pode, por exemplo, criar documentações para as funções do seu pacote. Quando outras pessoas o instalarem, elas poderão consultar esses manuais da mesma forma que fazem com qualquer outra função: ?funcao().

A documentação mais simples (e obrigatória) envolve dar um título para a função e descrever o que cada parâmetro significa. Para documentar uma função qualquer, basta adicionar comentários em cima dela com #' assim como no exemplo abaixo:

#' Função demonstrativa que soma e imprime
#'
#' @param x Um número ou vetor numérico
#' @param y Um número ou vetor numérico
#' @param ... Outros argumentos passados para [print()]
#'
#' @export
funcao_demo <- function(x, y, ...) {
  z <- x + y
  print(z, ...)
  return(z)
}

No RStudio esse tipo de documentação é tratado diferentemente de outros comentários, então certas palavras-chave ficam coloridas. @param por exemplo indica a documentação de um dos parâmetros e @export indica que aquela função será exportada pelo pacote, ou seja, ficará disponível ao usuário quando ele executar library(demo).

Para gerar a documentação do pacote, basta chamar uma outra função do devtools:

devtools::document()
#> Updating demo documentation
#> Updating roxygen version in ~/Documents/demo/DESCRIPTION
#> Writing NAMESPACE
#> Loading demo
#> Writing NAMESPACE
#> Writing funcao_demo.Rd

?funcao_demo()
#> Rendering development documentation for 'funcao_demo'

Conforme o número de funções no pacote for crescendo, basta iterar nesse ciclo descrito até aqui. Além disso, é importante lembrar (como destacado na sessão anterior) que qualquer função utilizada de outro pacote deve ser invocada na forma pacote::funcao(); neste momento, o pacote em questão se tornará uma dependência do seu pacote e deve ser declarado como tal com usethis::use_package("pacote").

Para garantir que o R não encontrará nenhum problema no seu pacote, basta executar a função de verificação devtools::check(). Se nenhum defeito for encontrado, basta compartilhar o pacote com os seus colegas e instalá-lo com devtools::install_local().

devtools::check()
#> Updating demo documentation
#> Writing NAMESPACE
#> Loading demo
#> Writing NAMESPACE
#> ── Building ───────────────────────────────────────────────────────── demo ──
#> Setting env vars:
#> ● CFLAGS    : -Wall -pedantic -fdiagnostics-color=always
#> ● CXXFLAGS  : -Wall -pedantic -fdiagnostics-color=always
#> ● CXX11FLAGS: -Wall -pedantic -fdiagnostics-color=always
#> ─────────────────────────────────────────────────────────────────────────────
#> ✔  checking for file ‘/home/clente/Documents/demo/DESCRIPTION’ ...
#> 
#> [... omitido por brevidade ...]
#> 
#> ── R CMD check results ───────────────────────────────── demo 0.0.0.9000 ────
#> Duration: 8.2s
#> 
#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔

Testes automatizados

Antes de concluir a sessão sobre pacotes, se faz necessária uma breve menção aos testes automatizados. Eles são disponibilizados pelo pacote testthat e permitem que um programador verifique que seu código está atendendo às especificações. Testes unitários garantem que uma alteração pontual em algum ponto do código não vai alterar o comportamento de nenhuma outra parte, já que as outras funções ainda terão que passar nos seus próprios testes.

Para criar um conjunto de testes é necessário primeiro criar o ambiente para tal dentro do pacote. Depois disso, basta criar conjuntos individuais de testes para cada função.

usethis::use_testthat()
#> ✔ Adding 'testthat' to Suggests field in DESCRIPTION
#> ✔ Creating 'tests/testthat/'
#> ✔ Writing 'tests/testthat.R'
#> ● Call `use_test()` to initialize a basic test file and open it for editing.

usethis::use_test("funcao_demo")
#> ✔ Increasing 'testthat' version to '>= 2.1.0' in DESCRIPTION
#> ✔ Writing 'tests/testthat/test-funcao_demo.R'
#> ● Modify 'tests/testthat/test-funcao_demo.R'

Como é possível notar, o pacote testthat permite criar um arquivo de testes para funcao_demo() (neste caso tests/testthat/test-funcao_demo.R). Esse arquivo já vem com um teste padrão a título de demonstração, mas, depois de reescrito manualmente, um possível conjunto de testes para funcao_demo() seria o seguinte:

library(demo)

test_that("funcao_demo funciona", {

  expect_equal(funcao_demo(1, 2), 3)
  expect_equal(funcao_demo(-1, -2), -3)
  expect_equal(funcao_demo(1, -2), -1)

  expect_output(funcao_demo(1, 2), "3")

})

E o resultado da execução dos testes é o seguinte:

devtools::test()
#> Loading demo
#> Testing demo
#> ✔ |  OK F W S | Context
#> ✔ |   4       | funcao_demo
#> 
#> ══ Results ══════════════════════════════════════════════════════════════════
#> OK:       4
#> Failed:   0
#> Warnings: 0
#> Skipped:  0
#> 
#> Keep up the good work.