From a2a2ebb6498e519ad845130b796e239ec0472e4d Mon Sep 17 00:00:00 2001
From: Walmes Zeviani <walmes@ufpr.br>
Date: Mon, 21 Dec 2015 22:04:36 -0200
Subject: [PATCH] =?UTF-8?q?Inicia=20cap=C3=ADtulo=203=20de=20Estrutura=20d?=
=?UTF-8?q?o=20Pacote.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
cap03.Rmd | 550 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 550 insertions(+)
create mode 100644 cap03.Rmd
diff --git a/cap03.Rmd b/cap03.Rmd
new file mode 100644
index 0000000..64d655e
--- /dev/null
+++ b/cap03.Rmd
@@ -0,0 +1,550 @@
+---
+title: "Pacote R"
+author: "Fernando Mayer & Walmes Zeviani"
+---
+
+```{r setup, include=FALSE}
+library(knitr)
+
+opts_chunk$set(
+ dev.args=list(family = "Palatino"))
+
+options(width = 68)
+
+## Carrega as definições de sessão.
+source("config.R")
+rty <- "md"
+```
+
+****
+# Pacote R #
+
+ * O jeito mais fácil de tornar acessível o código.
+ * Publicar artigo com material suplementar na forma de pacote.
+
+****
+# *devtools* & *roxygen2* #
+
+ * Facilitam o desenvolvimento de um pacote R.
+ * Torna o processo mais simples para um usuário pouco experiente.
+ * Instalar os pacotes do CRAN e do GitHub.
+
+****
+# Estrutura de um pacote R #
+
+Basicamente um pacote do R é uma convenção para organizar e padronizar a
+distribuição de funções extras do R. Todo pacote é composto
+*obrigatoriamente* por apenas dois diretórios e dois arquivos de meta
+dados:
+
+ * `R/`: um diretório contendo as funções em arquivos `*.R` (ex.:
+ `foo.R`).
+ * `man/`: um diretório contendo a documentação (páginas de ajuda) de
+ cada função do diretório acima. Os arquivos de documentação do R
+ terminam com a extensão `.Rd` (ex.: `foo.Rd`).
+ * `DESCRIPTION`: um arquivo texto contendo as informações sobre o seu
+ pacote: título, descrição, autor(es), licença, pacotes do qual
+ dependende, etc.
+ * `NAMESPACE`: um arquivo texto que informa quais funções do seu
+ pacote serão exportadas, ou seja, aquelas que estarão disponíveis
+ para o usuário, e quais funções são importadas de outros pacotes dos
+ quais o seu depende.
+
+Outros componentes que não são obrigatórios, mas podem estar presentes
+no pacote são:
+
+ * `tests/`: um diretório contendo *scripts* com testes unitários,
+ rodados durante a criação do pacote, para testar se existe algum
+ resultado não esperado sendo retornado por alguma de suas funções.
+ * `vignettes/`: um diretório que contém uma ou mais *vignettes*, que
+ traduzidas literalmente são como "vinhetas", pequenos (ou mesmo
+ grandes) textos que explicam com mais detalhes como os usuários
+ podem usar as funções de seu pacote.
+ * `data/`: um diretório contendo arquivos de dados (normalmente em
+ formato binário e comprimido do R, `.rda` ou `.RData`), que podem
+ ser usados como exemplos para aplicação das funções do pacote.
+
+Ainda são comuns diretórios `demo/`, `src/` e
+`data-raw/`. TODO-descrever.
+
+Caso você queira começar a contruir um pacote, as opções são: 1) criar
+todos os componentes (diretórios e arquivos) manualmente e ir
+alimentando com conteúdo, ou 2) usar a função `create()` do pacote
+`devtools` para criar a estrutura inicial, com os arquivos e diretórios
+fundamentais, de um pacote. Nesse guia optaremos pela segunda opção pela
+já justificada praticidade. Portanto:
+
+```{r create, comment=NA, include=FALSE, purl=FALSE}
+library(devtools)
+if (dir.exists(paths="./meupacote")) {
+ unlink("./meupacote/", recursive = TRUE, force = TRUE)
+}
+```
+```{r, comment=NA, eval=TRUE}
+## Carrega o pacote devtools.
+library(devtools)
+packageVersion("devtools")
+
+## Cria o pacote.
+create("meupacote", rstudio = FALSE)
+```
+```{r, include=FALSE}
+## Guarda no NAMESPACE vazio para exibir lá na frente.
+namespace <- readLines("./meupacote/NAMESPACE")
+```
+
+Versões do pacote `devtools` anteriores à 1.9.1 não criam
+automaticamente o arquivo `DESCRIPTION`, apenas criam o diretório `R/` e
+o arquivo `NAMESPACE`. Em caso de você estar com uma versão defazada do
+`devtools`, instale a mais recente do
+`r renderUrl("CRAN","https://cran.r-project.org/web/packages/devtools/index.html",rty)`
+(estável) ou de desenvolvimento no GitHub do
+`r renderUrl("autor","https://github.com/hadley/devtools",rty)`.
+
+Como pode ser observado na saída acima, esse comando cria um diretório
+chamado `meupacote`, contendo os arquivos `DESCRIPTION` e `NAMESPACE` e
+o diretório `R/`.
+
+```{r, echo=FALSE, comment=NA}
+cat(system("tree --charset=ascii -F ./meupacote/ | head -n -2",
+ intern = TRUE),
+ sep = "\n")
+```
+
+O diretório `R/` é criado vazio, bem como o arquivo `NAMESPACE`. Já o
+arquivo `DESCRIPTION` é criado com algumas informações de sugestão.
+
+```{r, echo=FALSE, comment=NA}
+cat(readLines("./meupacote/DESCRIPTION"), sep = "\n")
+```
+
+Todo pacote precisa ter o arquivo que o descreve, o `DESCRIPTION`. Uma
+forma fácil de criá-lo já com informações do seu pacote, é usando a
+função `write.dcf()` (dfc: `Debian control format`) ou o comando
+`cat()`, como é ilustrado a seguir. Depois de criado, sinta-se livre
+para abrir com seu editor favorito, editar e ampliar.
+
+```{r, eval=FALSE}
+write.dcf(
+ list(Package = "meupacote",
+ Title = "Meu Primeiro Pacote R",
+ Version = "0.0-1",
+ Author = "Fernando Mayer <fernandomayer@ufpr.br>",
+ Description = "O que esse pacote faz",
+ Depends = sprintf("R (>= %s)", getRversion()),
+ License = "GPL-3",
+ LazyData = "true"),
+ file = "meupacote/DESCRIPTION"),
+ indent = 4)
+
+cat()
+```
+```{r}
+cat(file = "meupacote/DESCRIPTION", sep = "\n",
+ sprintf('Package: meupacote
+Title: Meu Primeiro Pacote R
+Version: 0.0-1
+Authors@R: as.person(c(
+ "Fernando de Pol Mayer <fernando.mayer@ufpr.br> [aut,cre]",
+ "Walmes Marques Zeviani <walmes@ufpr.br> [aut]"))
+Description: Esse é o primeiro pacoteque estamos fazendo. Nesse tutorial
+ o pacote será desenvolvido com funções, dados e vinheta.
+Depends:
+ R (>= %s)
+License: GPL-3
+URL: http://git.leg.ufpr.br/leg/prr
+BugReports: http://git.leg.ufpr.br/leg/prr/issues
+LazyData: true
+Encoding: UTF-8', getRversion()))
+```
+
+Abaixo serão especificados os detalhes para a criação de cada um dos
+componentes exibidos acima.
+
+## `DESCRIPTION`: Caracterização do pacote ##
+
+Como você já deve supor, o arquivo `DESCRIPTION` caracteriza o seu
+pacote: quem é (são) o(s) autor(es), uma breve descrição do que ele faz,
+qual o tipo de licença, quais pacotes são necessários para que o seu
+funcione, e mais alguns detalhes.
+
+No arquivo `DESCRIPITION` uma série de
+`r renderUrl("campos","http://r-pkgs.had.co.nz/description.html",rty)` é
+permitida. Cada linha representa um campo, alguns obrigatórios (*) e
+outros opcionais (#), e após os dois pontos é o valor. Campos que
+excedem uma linha devem ser indentados.
+
+ * `Package` (*): é o nome do pacote. Não deve conter espaços, deve
+ começar com uma letra e o restante deve ser
+ alfanumérico. Caracteres especiais, como pontuações e acentos, não
+ são permitidos.
+ * `Title` (*): é o título do seu pacote. Recomenda-se que, por ser um
+ título, seja curto e informativo.
+ * `Version` (*): é a versão do pacote. A versão inicia (ou atual do
+ pacote). O versionamento de qualquer pedaço de software é uma coisa
+ muito importante e não há um consenso de que exista um padrão para
+ todos os casos. No entanto, nos pacotes do R, recomenda-se que as
+ versões sejam do tipo `x.y-z` ou `x.y.z` onde `x` seria o contador
+ de versão "maior", `y` de versão "menor", e `z` de "patches"
+ (alterações menores no código, como correção de bugs por exemplo).
+ * `Author` ou `Authors@R` (*): lista os criadores, autores e
+ colaboradores do pacote. Existem várias formas de preencher esse
+ campo, sendo a mais simples àquele para um único autor e as duas
+ opções a seguir, equivalentes, para projetos coletivos.
+
+ Authors@R: c(
+ person("Hadley", "Wickham",
+ email = "hadley@rstudio.com",
+ role = "cre"),
+ person("Winston", "Chang",
+ email = "winston@rstudio.com",
+ role = "aut"))
+
+ Authors@R: as.person(c(
+ "Hadley Wickham <hadley@rstudio.com> [aut, cre]",
+ "Winston Chang <winston@rstudio.com> [aut]"))
+ O argumento `role` é importante pois é ele que identifica o papel
+ de cada autor no desenvolvimento do pacote. Por padrão, é
+ necessário ter um (e somente um) autor (`"aut"`) e um mantenedor
+ (`"cre"`), que pode ou não ser a mesma pessoa. Outros papéis, como
+ por exemplo o de um contribuidor (`"ctb"`), e outros detalhes dessa
+ função estão em `?person`. O criador ou mantenedor (`"cre"`) é
+ quase sempre o principal desenvolvedor do projeto, responsável pela
+ gestão e quem recebe notificações de *bugs*, por exemplo. O autor
+ (`"aut"`) é quem dá contribuições grandes ao projeto. O colaborador
+ `"ctb"` é quem dá contribuições menores, ocasionais. Pelo menos um
+ dos listados no campo autor deve ser o mantenedor (`[cre]`) para
+ evitar erros durante produção do pacote.
+ * `Description` (*): Uma descrição um pouco mais detalhada sobre o que
+ o seu pacote faz. É preciso ter pelo menos duas frases completas
+ (sim, o R confere isso), mas não muito maior do que um parágrafo,
+ algo com não mais de 10 linhas.
+ * `Imports` (#): é um campo para listar os pacotes do qual o seu
+ obrigatoriamente precisa. A lista de pacotes é separada por
+ vírgula, em geral um por linha. Aqui entram aqueles pacotes cujas
+ funções são usadas por você dentro das suas funções. Quando o seu
+ pacote for instalado, esses pacotes devem estar presentes. Aqueles
+ que são do CRAN (oficiais) são instados automaticamente. O usuário
+ deve instalar previamente àqueles que não forem oficiais, como
+ muitos no github e bioconductor. TODO:verificar Colocar um pacote
+ nesse campo garante que o pacote estará **instalado**, mas não que
+ ele será carregado toda que vez que o seu pacote for
+ carregado. Para utilizar funções de outros pacotes corretamente é
+ necessário especifições da forma `pacote::funcao()` ou então
+ utilizar o arquivo `NAMESPACE` conforme veremos abaixo.
+ * `Depends` (#): esse campo é muito similar ao anterior. A diferença é
+ que pacotes no `Imports` são carregados (*loaded*) e no `Depends`
+ são anexados (*attached*).
+ Dada essa diferença mínima, é muito comum só haver o campo
+ `Imports`. É comum o `Depends` indicar a versão do R que o seu
+ pacote depende. É sempre prudente colocar uma versão que seja maior
+ ou igual a versão que você está desevolvendo o pacote. Em ambos
+ campos é possível indicar a versão mínima exigida dos pacotes,
+ conforme abaixo.
+
+ Depends:
+ R (>= 2.15),
+ lattice
+ Imports:
+ ggplot2,
+ Matrix (>= 1.2.0),
+ methods
+ * `Suggests` (#): é para listar os pacotes do qual o seu tira
+ proveito, mas que não são exigências. Aqui entram pacotes do qual o
+ seu chama uma função ou *dataset* na sessão exemplos da
+ documentação. O usuário precisará instalar aqueles que não
+ possuir. Diferente daqueles no `Imports` os pacotes listados aqui
+ não serão instalados junto com o seu. Eles podem ser usados, mas
+ não são necessários. Por exemplo, você pode usar um pacote apenas
+ para usar alguma base de dados ou apenas uma função. Use esse campo
+ apenas se o seu pacote puder funcionar mesmo sem os pacotes
+ especificados.
+ * `License` (#): A licença é fundamental se você pretende compartilhar
+ o seu pacote. Algumas opções comuns são: `CC0` (nenhum tipo de
+ restrição), `MIT` (prevê atribuição mas é bastante permissiva), e
+ `GPL-3` (a mais utilizada, requer que qualquer trabalho derivado do
+ seu seja distribuido com a mesma licença). Para mais opções e
+ detalhes sobre licenças de software livre, consulte
+ <http://choosealicense.com>.
+ * `LazyData` (#): Essa opção somente é importante se você pretende
+ distribuir algum conjunto de dados com o seu pacote (arquivos
+ `.rda` no diretório `data/`). Com a opção acima, os dados só serão
+ carregados se realmente forem chamados (com a função `data()`), e
+ não carregados na inicialização do pacote. Isso garante mais
+ agilidade para carregar o pacote e economiza memória caso os dados
+ não sejam utilizados (especialmente se as bases de dadpos forem
+ gandes).
+ * `URL` (#): um site de referencia onde você hospeda o pacote, por
+ exemplo.
+ * `BugReports` (#): normalmente endeços para sistemas de controle de
+ versão, como github e gitlab, onde os usuários podem submeter os
+ *bugs*.
+ * `Encoding` (#): É um campo extremamente necessário para nós de
+ lingua latina pois permite acentos na documentação do pacote,
+ testos de comentários, etc. Desenvolvedores Linux usam `UTF-8`.
+ * `VignetteBuilder` (#): Habilitou-se o uso do `knitr` a partir da
+ versão 3.0.0 do R para produção de
+ `r renderUrl("vinhetas","http://yihui.name/knitr/demo/vignette/",rty)`.
+ Estas podem ser escritas em RMarkDown (para html ou pdf), além de
+ ainda manter RLatex. Antes vinhetas tinham que ser feitas em
+ Sweave. Esse campo serve para indicar o pacote `knitr`, que também
+ deve aparecer, pelo menos, no campo `Suggests` também.
+
+Para podermos utilizar esse arquivo para de fato gerarmos um pacote de
+exemplo ao final deste tutorial, vamos modificar alguns campos e
+utilizar o seguinte arquivo `DESCRIPTION`:
+
+## `R/`: Funções
+
+O diretório `R/` irá conter apenas as funções (arquivos `.R`) do seu
+pacote. As funções podem estar em vários arquivos `.R` separados (um
+para cada função) ou em arquivos com várias funções cada. A escolha é
+mais uma questão de preferência pessoal, mas como veremos mais adiante,
+utilizar arquivos separados para as funções torna o processo de
+documentação um pouco mais ágil, além de facilitar a manutenção do
+pacote com o tempo.
+
+Para exemplificar, vamos criar uma função simples para resolver um
+problema bem conhecido: calcular a hipotenusa de um triângulo retângulo
+a partir dos catetos, cuja solução se baseia no Teorema de
+Pitágoras. Vamos colocar a função no diretório diretório `R/` com o nome
+`pitagoras.R`.
+
+```{r, eval=FALSE}
+pitagoras <- function(a, b){
+ h <- sqrt(a^2 + b^2)
+ return(h)
+}
+```
+```{r, include=FALSE}
+file.copy(from = "./aux/pitagoras.R", to = "./meupacote/R/pitagoras.R")
+```
+
+Com a função pronta, possivelmente iremos (e devemos) testá-la. Para
+carregá-la executamos a função `load_all()` do pacote `devtools` em uma
+seção do R com diretório de trabalho apontando para o arquivo
+`DESCRIPTION`.
+
+```{r, echo=TRUE, eval=FALSE}
+## Carrega todas as funções do pacote. Assume estar em meupacote/.
+load_all()
+```
+```{r, echo=FALSE, eval=TRUE}
+load_all("meupacote/")
+```
+```{r}
+## Note que o package:meupacote foi carregado.
+search()
+
+## Os objetos exportados estão disponíveis.
+ls("package:meupacote")
+
+## class(pitagoras); formals(pitagoras); body(pitagoras)
+pitagoras
+```
+
+Essa instrução irá carregar todas as funções que estiverem dentro do
+diretório `R/`, tornado-as disponíveis para uso. Além disso carrega os
+datasets do diretório `data/` que veremos adiante.
+
+Se utilizassemos a função `source("R/pitagoras.R")` para carregar a
+função teria o mesmo efeito: as funções estariam disponíveis para
+uso. No entanto, se tivermos vários arquivos, e/ou estivermos testando
+alterações em muitas funções, a função `load_all()` é bem mais
+conveniente. Além do mais, as funções carregas com `load_all()` ficam no
+*enviroment* do pacote (`package:meupacote`) e não no *workspace* junto
+aos objetos de você cria durante a sessão, o `.GlobalEnv`.
+
+Para melhorar ou corrigir as funções, basta fazer as nos arquivos `.R`,
+carregá-las com `load_all()` e testar novamente. Esse processo
+geralmente se repete muitas vezes durante o desenvolvimento de um
+pacote.
+
+## `man/`: Documentação
+
+Você deve ter notado que o diretório `man/` não é criado da mesma forma
+que os demais quando utilizamos a função `create()`. Isso porque esse
+diretório depende das funções, quatidade e nomes, que serão criadas
+dentro do diretório `R/`. No entanto, ele também é obrigatório para
+podermos criar um pacote mínimo.
+
+Como mencionado anteriormente, a documentação de funções do R segue um
+formato muito parecido com o LaTeX (mas com alguns comandos
+próprios). Cada função criada dentro do diretório `R/`, independente de
+estar em um arquivo separado ou único (com várias funções), deve
+**obrigatoriamente** ter um arquivo correspondente dentro do diretório
+`man/`, com a extensão `.Rd`. Em outras palavras, mesmo que você decida
+manter funções no mesmo arquivo em `R/`, as documentações delas estarão
+em arquivos separdas em `man/`. Fica um pouco difícil de manter
+correspondência e por isso é comum ter uma função por arquivo em
+`R/`. Existes excessões.
+
+Sendo assim, a nossa função de exemplo acima, que está em um arquivo
+chamado `pitagoras.R`, precisa de um arquivo `pitagoras.Rd` dentro do `man/` para
+documentá-la.
+
+Existem duas formas de documentar uma função com os arquivos `.Rd`: uma
+é da maneira tradicional, escrevendo manualmente a documentação
+utilizando a linguagem específica e colocando os campos necessários. Os
+detalhes de como fazer isso manualmente estão em
+`r renderUrl("Writing R documentation files","http://cran.r-project.org/doc/manuals/r-release/R-exts.html",rty)`.
+Outra forma de escrever a documentação de uma função é utilizando o
+pacote `roxygen2`, que utiliza algumas etiquetas, ou *tags*, simples e
+permite que você escreva a documentação dentro do próprio arquivo
+`.R`. Dessa forma fica muito mais simples alterar ou atualizar a
+documentação de uma função, pois tudo se concentra dentro de um único
+arquivo.
+
+Neste texto vamos utilizar o pacote `roxygen2` para gerar a documentação
+das funções. O primeiro passo é escrever a documentação dentro do
+arquivo `.R`. A documentação usando o `roxygen2` segue o seguinte
+formato:
+
+ * Toda documentação começa com um comentário especial, do tipo `#'`
+ (note o `'` depois do `#`).
+ * Os campos de documentação são criados a parir de etiquetas (*tags*)
+ que iniciam com `@`, colocados logo após um comentário especial
+ `#'`.
+ * Toda a documentação deve ficar diretamente acima do início da
+ função.
+
+A documentação com o `roxygen2` da nossa função `pitagoras()` é exibida
+a seguir.
+
+```{r, echo=FALSE, comment=NA}
+cat(readLines("meupacote/R/pitagoras.R"), sep = "\n")
+```
+
+Para gerar a documentação, basta utilizar a função `document()` do
+pacote `devtools`.
+
+```{r, echo=TRUE, eval=FALSE}
+## Gera/autualiza do diretório man/ com as documentações.
+document()
+```
+```{r, echo=FALSE, eval=TRUE}
+document("meupacote/")
+```
+```{r, echo=FALSE, comment=NA}
+cat(system("tree --charset=ascii -F ./meupacote/ | head -n -2",
+ intern = TRUE),
+ sep = "\n")
+```
+
+O resultado da chamada dessa função é:
+
+ * Criar o diretório `man/` se ele ainda não existir, ou se for a
+ primeira vez que estiver criando a documentação com a função
+ `document()`.
+ * Gerar os arquivos `.Rd` dentro de `man/` (se ainda não existirem)
+ correspondentes às funções no diretório `.R`.
+ * Se os arquivos `.Rd` já existirem, a chamada da função `document()`
+ irá apenas atualizar os arquivos que foram modificados.
+ * Escrever no arquivo `NAMESPACE` as funções a serem exportadas ou
+ importadas. Veremos mais detalhes abaixo na seção `NAMESPACE`.
+
+Vale ressaltar que o comando `document()` do pacote `devtools` é de fato
+um "wrapper" para a função `roxygenize()` do pacote `roxygen2`.
+
+No nosso exemplo, a chamada da função `document()` criou o diretório
+`man/` e gerou o arquivo `pitagoras.Rd`. Note que é muito mais simples
+escrever com o `roxygen2` do que ter que editar esse arquivo todo a
+mão. Note também o comentário no início desse arquivo. O `roxygen2`
+deixa claro que você não deve (e não precisa) modificar esse arquivo
+`pitagoras.Rd` para atualizar a documentação. Sempre que alterar alguma
+coisa faça no próprio arquivo `.R`, e a função `document()` irá
+atualizar a documentação no arquivo `.Rd`.
+
+```{r, echo=FALSE, comment=NA}
+cat(readLines("./meupacote/man/pitagoras.Rd"), sep = "\n")
+```
+
+Para conferir se a documentação está de acordo com o que você espera, a
+qualquer momento, peça a documentação com `?pitagoras` ou
+`help(pitagoras)`. Lembre-se de rodar a função `load_all()` para
+carregar a documentação atualizada depois de `document()`.
+
+Uma outra forma mais automática de conferir se a documentação está
+escrita de maneira correta, é utilizando a função `check_doc()` do
+pacote `devtools`. Essa função avalia a consistência dos campos, se não
+ficaram argumentos sem descrição, campos obrigatórios omissos, chaves
+sem fechar, etc.
+
+```{r, echo=TRUE, eval=FALSE}
+check_doc()
+```
+```{r, echo=FALSE, eval=TRUE}
+check_doc("meupacote/")
+```
+
+Se nenhuma mensagem de aviso ou erro apareceu acima, então a
+documentação está de acordo com o esperado, sintaticamente.
+
+Alguns detalhes das etiquetas utilizadas nesse exemplo do
+`roxygen2` (<http://r-pkgs.had.co.nz/man.html>):
+
+ * `@title`: um título curto da função (deve ser capitalizado).
+ * `@name`: o nome da função.
+ * `@description`: descreve o que a função faz e pra que ela serve, de
+ maneira geral.
+ * `@param`: descreve o que cada argumento da função faz. Deve ser
+ sempre no formato: `@param argumento descrição do argumento`. Quando
+ vários argumentos podem ser descritos juntos, eles devem ser
+ separados por vírgula mas sem espaços.
+
+ @param title título do gráfico
+ @param x,y,z vetores de observações
+ @param ... argumentos passados para a função plot.
+ * `@details`: espaço para escrever mais detalhes, geralmente mais
+ técnicos, sobre a sua função, e/ou para detalhar alguma coisa
+ específica de algum argumento.
+ * `@return`: especifica o que a sua função retorna (um gráfico, uma
+ lista, um número, um vetor, um objeto de determinada classe).
+ * `@author`: autr(es) da função.
+ * `@seealso`: outras funções que podem ser úteis para quem está usando
+ a sua função, ou funções similares. No exemplo acima temos duas
+ marcações que são específicas da documentação do R: `\code{}` para
+ que o texto dentro das chaves saia com fonte monoespaço e verbatim
+ (`como esta`), geralmente para especificar nomes de funções, etc.;
+ `\link[<pacote>]{<função>}` faz o link para a página de ajuda de
+ alguma `<função>` dentro de algum `<pacote>`. Mais marcações do
+ formato `.Rd` podem ser encontradas no manual de documentação do R,
+ e podem ser utilizadas dentro na documentação com `roxygen2`.
+ * `@example`: exemplos de uso da sua função.
+ * `@export`: esta tag é a responsável por sua função ficar disponível
+ para os usuários, e é o que faz a função ser incluida no `NAMESPACE`
+ (mais detalhes serão vistos na seção `NAMESPACE` abaixo). Se você
+ não quer que a função seja disponibilizada para os usuários quando
+ carregarem o seu pacote (em funções internas ou auxiliares por
+ exemplo), simplesmente não inclua esta tag na documentação.
+ * `@source` É um campo considerado na documentação de *datasets* para
+ indicar a fonte dos mesmos. Geralmente contém uma url.
+ * `@references` É um campo para indicar publicações ou outros tipos de
+ referências com relação ao objeto documentado.
+
+Existem ainda campos permitidos que não foram aqui mencionados. A
+`r renderUrl("vinheta","https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html",rty)`
+do pacote `roxygen2`
+lista todo o conjunto enquanto que uma referência fácil é o
+`r renderUrl("*Cheat Sheet*","https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf",rty)`
+do pacote `devtools`.
+
+## `NAMESPACE`: Organização
+
+<!-- http://r-pkgs.had.co.nz/namespace.html -->
+
+O `NAMESPACE` é um arquivo que ajuda a organizar as funções exportadas e
+importadas pelo seu pacote. Ele ajuda um pacote a ser auto contido, no
+sentido de que ele não vai interferir no funcionamento de outros
+pacotes, e que também os outros pacotes não irão interferir no
+funcionamento do seu.
+
+Normalmente, a especificação do `NAMESPACE` é a parte mais difícil da
+criação de um pacote, mas com o uso do `devtools` como estamos fazendo,
+normalmente não será necessário se preocupar com todos os detalhes que
+envolvem esse arquivo. O mais importante é saber quais funções serão
+exportadas do seu pacote, quais serão importadas, e de que maneira
+podemos especificar essas funções.
+
+****
+# Começando um pacote #
--
GitLab