C ++: Criando documentação com Doxygen

A maioria dos programadores odeio para criar documentação até 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.

Instalando Doxygen

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

Faça o download 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.

Agora inicie Code :: Blocks. Seleccione DoxyBlocks-Abra as Preferências. 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: Arquivos de Programas doxygen bin doxygen.exe. Faça o mesmo para o caminho para doxywizard. Aqui, o padrão para o Windows é C: Program Files doxygen bin doxywizard.exe. Você pode deixar as outras ferramentas em branco como eles não são necessários ao gerar documentação em formato HTML.

Adição de comentários da documentação

Doxygen utiliza 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-Abra as Preferências 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 aborrecido.ru/extras/cplusplus):

/ ** Breve ** list 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 da função que se segue imediatamente. Doxygen palavras-chave começar com um (Barra invertida). o breve bandeiras de palavras-chave A breve descrição da função. A breve descrição pode estender-se ao longo de mais do que uma linha. Esta deve ser uma breve descrição da função que aparece em telas tabulares.

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 do 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 um novo Poupança * ou Verificação objeto de conta e adiciona-o à lista * conta. . Um X termina a entrada. Qualquer outra entrada * é assumido como sendo um depósito (número superior a 0 *) ou uma retirada (números inferiores a 0). ** Lista param accList 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 os membros de dados. Coloque o cursor no final da linha e selecionar-Line DoxyBlocks 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:

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

documentação geradora 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 selecione 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. Seleccione DoxyBlocks-Abra as Preferências e, em seguida, selecione a guia Padrões Doxyfile. Certifique-se de que o extrato Todos caixa está marcada. Em seguida, selecione a guia Doxyfile Padrões 2 e marque a caixa de seleção Class_Diagrams. Agora, selecione a guia Geral e marque a opção Executar HTML Após a 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.)

Selecione Documentação DoxyBlocks-Extract para gerar e visualizar a documentação. Depois de um relativamente curto intervalo, Doxygen abre seu navegador favorito com 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 só 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 que o 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 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, seguido da descrição detalhada, os parâmetros, e o valor de retorno:

A documentação da classe é semelhante completa como mostrado pelo seguinte trecho de código.

/ ** Classe Account * informar uma conta bancária abstrato * detalhes Esta classe abstrata incorpora * propertiescommon a ambos os tipos de contas:. * Correntes e de poupança. No entanto, ele está faltando o * conceito de 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 de herança entre Conta, suas classes pai, e suas classes infantis.