Integração do pacote R com código C ++ reutilizável moderno usando Rcpp – Parte 6

cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br


Na discussão a seguir, veremos uma maneira rápida e relativamente fácil de fornecer documentação para cada uma das funções C ++ que são exportadas como uma função R em um Rcpppacote baseado em Deve-se notar que existem alternativas que são freqüentemente preferidas para pacotes que são submetidos ao CRAN para publicação; por exemplo, usando o ROxygen2 pacote para gerar a documentação de instruções embutidas no código da interface. Isso, no entanto, envolve sofisticação e complexidade além do escopo desta série de “primeiros passos”.

A abordagem que examinaremos aqui envolve o preenchimento de um modelo de arquivo para cada função exportada, bem como um arquivo que fornece informações comuns a todo o pacote. Esses modelos de arquivo carregam um Rd extensão, como veremos. Os arquivos html correspondentes são gerados quando você constrói seu pacote. A boa notícia é que RStudio torna este um processo relativamente indolor.

Se você criar um Rcpp projeto de pacote, conforme discutido nas postagens anteriores desta série, você encontrará os dois arquivos a seguir fornecidos por padrão sob o man subdiretório:

Esses arquivos são fornecidos por padrão. Em última análise, você não precisará do Olá Mundo arquivo de ajuda, mas o RcppProject-package.Rd conterá informações comuns para todo o pacote; este último arquivo será apresentado em breve.

Documentação para funções exportadas

Vamos primeiro cobrir como criar um arquivo de ajuda para um arquivo exportado Rcpp função de interface. Para mostrar isso, vamos voltar ao código de amostra fornecido no GitHub para a Parte 5. Suponha que você queira fornecer a documentação para o rAdd(.) função que é exportada do CppInterface.cpp Arquivo. Como você faria isso?

Leia Também  Esqueça o plano B, a falha não é uma opção

Com o RStudio, a solução é bastante fácil. Primeiro, você selecionaria New File/Documentation... de File menu no topo:

Selecione um novo arquivo de documentação

Você verá um painel de entrada como segue. Sob Nome do tópico, digite o nome da função rAdd, e certifique-se de que a seleção em Modelo Rd está configurado para function (o padrão):

Nova seleção de arquivo de documentação R

Depois de clicar OK, você verá o rAdd.Rd arquivo aparece no man subdiretório no painel de arquivos RStudio:

Novo arquivo de documentação em man pasta

Em seguida, clique duas vezes neste arquivo para abri-lo no RStudio. Observe que o RStudio é inteligente o suficiente para coletar o número adequado de argumentos da função e colocar essas informações no arquivo:

Top do criado rAdd.Rd Arquivo

cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br

Trabalhe seção por seção do arquivo e substitua os comentários em verde (começando com um % personagem) com as informações relevantes conforme descrito para preencher as informações necessárias; também, a linha comentada: %- Also NEED an 'alias' for EACH other topic documented here. pode apenas ser removido. O conteúdo de cada seção deve ser colocado dentro das chaves { } seguindo cada um dos itens a seguir, conforme será demonstrado no exemplo a seguir a essas descrições.

name e alias: Deixe como estão, com o nome da função.

title: Forneça uma breve descrição do que a função faz.

description: Forneça uma descrição mais detalhada do que a função faz.

usage: A coisa mais fácil de fazer aqui é deixar como está.

arguments: Você notará a descrição de cada argumento x e y está aninhado. Basta inserir o tipo de cada variável e uma breve descrição de cada uma, se desejar.

details: Isso pode ser removido se não forem necessários mais detalhes; caso contrário, coloque detalhes adicionais sobre a funcionalidade aqui.

Leia Também  How I Taught Scientific Blogging with R Markdown, Online

value: Indique o tipo de retorno aqui.

references: Coloque as referências que deseja citar aqui; caso contrário, ele pode ser removido se não for necessário.

author: Forneça os nomes dos autores / contribuidores para esta função de pacote.

note e seealso: Insira qualquer informação adicional sobre a função; pode ser removido se não for necessário.

examples: Coloque aqui o (s) exemplo (s) de trabalho da sua função. Deve ser totalmente autocontido, incluindo quaisquer dados de entrada (se necessário).

Após a seção de exemplos, remova os comentários finais na parte inferior do arquivo.

Um arquivo de amostra completo poderia ser o seguinte. Você também pode usar isso como um modelo para a documentação de sua própria função, se desejar.

name{rAdd}
alias{rAdd}
title{Add two numbers}
description{Adds two real numbers}
usage{
rAdd(x, y)
}
arguments{
  item{x}{A real number}
  item{y}{A real number}
}
details{This is a trivial example}
value{numeric}
references{Courant and Hilbert, Methods of Mathematical Physics, Volumes 1 & 2}
author{Fred Sanford}
note{Nothing to say}
seealso{https://rviews.rstudio.com/}
examples{
x 

To generate the html help file, rebuild your project. When complete, and with the package reloaded into your current R session, look up rAdd in the usual help section in RStudio. The result should look like this:

The generated help file for the rAdd(.) function

As a matter of best practice, you will want to follow the same instructions per the above for all of the remaining exported interface functions in your package. The remaining .Rd files have been uploaded to the man directory in the GitHub repository for this post. These help files accompany the source files that were provided for Part 5.

Documentação de informações comuns do pacote

Um arquivo padrão também é fornecido com um RStudio Rcpp projeto que deve conter um arquivo de ajuda geral para todo o pacote; é da forma PackageName-package.Rd. No entanto, modificar este arquivo para seu pacote específico pode às vezes ser uma fonte de erros de construção e de verificação de pacote, então eu recomendo apenas mantê-lo simples, pelo menos até que você se acostume mais a escrever seus próprios pacotes R. Em particular, você provavelmente evitará problemas removendo a seção de exemplos de código deste arquivo e relegando-os aos arquivos de ajuda de função individuais, pelo menos para começar.

Leia Também  Atualizações empolgantes dos meus 4 pacotes principais do Shiny

Por exemplo, o RcppBlogCode-package.Rd O arquivo também está incluído na pasta GitHub desta postagem, conforme observado acima. Como você pode ver, isso é curto e agradável, mas se aplicado a uma situação realista, deve ser razoavelmente informativo. O resultado gerado é mostrado aqui:

Arquivo de ajuda gerado contendo informações comuns do pacote



cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br