C ++: criando documentação com doxygen

A maioria dos programadores odeia para criar documentação ainda mais do que eles odeiam a comentar o seu próprio código. Digite Doxygen, que permite aos programadores para incorporar as tags nos comentários, que podem posteriormente ser extraídos para criar a documentação.

Video: Tutorial Doxygen - Criando a documentação do seu programa

Instalando Doxygen

não Doxygen não vem com o Code :: Blocks (pelo menos não como desta escrita). Você precisa baixar a versão apropriada do Doxygen para a sua aplicação. (Há também um link para o site Doxygen a partir do site Code :: Blocks.) Depois de conectar-se a website Doxygenorg, você pode navegar até a página de download e encontrar a versão do Doxygen para seu sistema operacional, como mostrado aqui:

Baixe e instale a versão que é certo para o seu sistema operacional. Você pode aceitar os padrões, mas lembre-se que o assistente de instalação coloca o arquivo executável Doxygen.

Video: Tutorial Doxygen [Códigos em C]

Agora inicie Code :: Blocks. Selecione Preferências DoxyBlocks → Abertas. De lá, selecione a guia Geral e definir o caminho para Doxygen. (Este é o caminho que anotou no parágrafo anterior.) O caminho padrão para Windows é C: Program Filesdoxygenbindoxygen.exe. Faça o mesmo para o caminho para doxywizard. Aqui, o padrão para o Windows é C: Programa Filesdoxygenbindoxywizard.exe. Você pode deixar as outras ferramentas em branco como eles não são necessários ao gerar documentação em formato HTML.

Adicionando Documentação Comments

Doxygen usa comentários especiais para palavras-chave bandeira que ajudam a ferramenta criar documentação. Desconcertante suficiente, Doxygen aceita vários padrões diferentes, mas o padrão é a que mais se assemelha JavaDoc, o / ** comentar, o que é bom. (Você pode mudar o estilo de comentário a um dos outros, selecionando DoxyBlocks → Preferências Abrir e, em seguida, selecionando a guia Comentário Style.)

Para ver como isso funciona, coloque o cursor no início de uma função e selecione DoxyBlocks → bloco de comentário (ou pressione Ctrl + Alt + B). Um comentário como aparecem os seguintes (os seguintes exemplos estão usando o programa Budget5 que aparece no material para download em faqcartx.info/extras/cplusplus):

/ ** breve ** lista accList param&* Retornar void ** / void getAccounts (lista& accList) {

Code :: Blocks insere um bloco de comentário Doxygen começando com / **. Doxygen sabe que este comentário pertence à definição de função que se segue imediatamente. Doxygen palavras-chave começar com um (Invertida). o breve bandeiras-chave A breve descrição da função. A breve descrição pode se estender por mais de uma linha. Esta deve ser uma breve descrição da função que aparece em telas tabulares.

Video: Tutorial - Doxygen

O programador pode seguir esta com uma descrição mais completa sinalizado com o detalhes palavra-chave. Esta descrição detalhada dá uma descrição mais completa do que a função faz.

Muitas das palavras-chave Doxygen são opcionais. Em particular, o detalhes palavra-chave é assumido se você iniciar um parágrafo separado da breve descrição por nada mais do que uma linha em branco.

Além do que é uma linha separada sinalizadas com a palavra-chave param para descrever cada argumento para a função. Finalmente, o Retorna palavra-chave descreve o valor retornado pela função.

Quando preenchido, o comentário Doxygen para getAccounts () pode aparecer como segue:

/ ** breves getAccounts - entradas contas a partir do teclado * detalhes Esta função lê a entrada do teclado * Para cada S ou C inserido, a função cria uma nova Poupança * ou Verificação objeto de conta e adiciona à lista * conta.. Um X termina a entrada. Qualquer outra entrada * é assumido como sendo um depósito (números superiores a 0 *) ou uma retirada (números de menos do que 0) ** lista accList param.& a lista de conta * objetos criados por getAccounts () * retornar void * / void getAccounts (lista& accList) {

Você também pode adicionar um comentário Doxygen na mesma linha. Esta é mais frequentemente usado ao comentar membros de dados. Coloque o cursor no final da linha e selecionar DoxyBlocks → linha de comentário ou pressione Ctrl + Alt + L. Agora preencha uma descrição do membro de dados. O resultado é mostrado no exemplo a seguir, também feita a partir de Budget5:

Video: Tutorial Doxygen(Doxywizard)

equilíbrio dupla - / ** lt; o saldo em conta corrente * /

documentação de geração Doxygen

Doxygen pode gerar a documentação em vários formatos diferentes, embora alguns (como HTML compilado) exigem mais downloads. O formato HTML é particularmente conveniente uma vez que requer nada mais do que um navegador para visualizar.

O padrão é HTML, mas se você quiser alterar o formato de escolha Preferências DoxyBlocks → Open, em seguida, selecione os padrões Doxyfile 2 guia. Nesta janela, você pode selecionar todos os diferentes formatos que você deseja gerar.

Antes de extrair documentação pela primeira vez, você provavelmente vai querer escolher algumas outras opções. Selecione Preferências DoxyBlocks → Abrir e, em seguida, selecione a guia Padrões Doxyfile. Certifique-se de que o Extract All caixa está marcada. Em seguida, selecione a guia Doxyfile Defaults 2 e verificar a caixa de seleção Class_Diagrams. Agora selecione a guia Geral e verifique o Run HTML Depois de caixa de Compilação. Clique OK, e está feito. (Você não vai precisar fazer isso de novo como as opções são salvos em um arquivo chamado Doxyfile.)

Seleccione DoxyBlocks → Documentação Extract para gerar e visualizar a documentação. Depois de um relativamente curto intervalo, Doxygen abre seu navegador favorito com a documentação como o mostrado na figura a seguir.

Doxygen não é muito amigável quando se trata de erros de entrada. Às vezes Doxygen simplesmente pára documentação gerando em algum momento de sua fonte para nenhuma razão óbvia. Verifique o arquivo doxygen.log contida no mesmo diretório do Doxyfile por quaisquer erros que possam ter ocorrido durante a extração.

A imagem seguinte mostra o navegador do projeto na janela à esquerda que permite ao usuário navegar dentro a documentação do projeto. À direita, o getAccounts () função foi selecionada a fim de obter uma descrição mais detalhada. A breve descrição aparece na primeira linha, seguida pela descrição detalhada, os parâmetros, eo valor de retorno:

A documentação da classe é semelhante minuciosa como mostra o seguinte trecho de código.

/ ** classe Account * informar uma conta bancária abstrato * detalhes Esta classe abstrata incorpora * propertiescommon a ambos os tipos de conta:. * Correntes e de poupança. No entanto, ele está faltando o * conceito retirada (), que é diferente * entre a Conta de dois * / class {

A documentação para Conta é mostrado aqui:

Observe a descrição que aparece sob a classe Conta. Esta é a descrição breve. Clicando mais vai levá-lo para a descrição detalhada. Observe também a representação gráfica da relação entre herança Conta, suas classes pai, e suas classes infantis.