C ++: Criando Documentação com Doxygen - dummies

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

Instalando Doxygen

O Doxygen não vem com Código:: Blocos (pelo menos não a partir desta gravação). Você precisará baixar a versão apropriada do Doxygen para sua aplicação. (Existe também um link para o site Doxygen do Código:: Blocks site.) Depois de vincular ao site Doxygenorg, você pode navegar até a página de download e encontrar a versão do Doxygen para o seu sistema operacional, conforme mostrado aqui:

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

Agora comece Código:: Blocos. Selecione DoxyBlocks → Open Preferences. A partir daí, selecione a guia Geral e defina o Caminho para o Doxygen. (Este é o caminho que você observou no parágrafo anterior.) O caminho padrão para o Windows é C: Program Filesdoxygenbindoxygen. exe. Faça o mesmo para o caminho para Doxywizard. Aqui, o padrão para Windows é C: Program Filesdoxygenbindoxywizard. exe . Você pode deixar as outras ferramentas em branco, pois elas não são necessárias ao gerar documentação em formato HTML.

Adicionando Comentários da Documentação

O Doxygen usa comentários especiais para sinalizar palavras-chave que ajudam a ferramenta a criar documentação. Com confusão suficiente, o Doxygen aceita vários padrões diferentes, mas o padrão é o que mais parece o JavaDoc, o comentário / ** , o que é bom. (Você pode alterar o estilo de comentário para um dos outros selecionando DoxyBlocks → Open Preferences e, em seguida, selecionando a aba Style de comentários.)

Para ver como isso funciona, coloque o cursor no início de uma função e selecione DoxyBlocks → Block Comment (ou pressione Ctrl + Alt + B). Um comentário como o seguinte aparece (os exemplos a seguir estão usando o programa Budget5 que aparece no material para download em www. Dummies. Com / extras / cplusplus):

/ ** breve * * lista de acesso de param & * return nulo * * / void getAccounts (list & accList) {

Código:: Blocks insere um comentário de bloco de Doxygen começando com / **. O doxygen sabe que esse comentário pertence à definição da função que segue imediatamente. As palavras-chave Doxygen começam com uma (barra invertida). A palavra-chave breve marca 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 exibições tabulares.

O programador pode seguir isso com uma descrição mais detalhada sinalizada com a palavra-chave detalhes . 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, a palavra-chave detalhes é assumida se você iniciar um parágrafo separado da breve descrição por nada mais do que uma linha em branco.

Além disso, é uma linha separada marcada com a palavra-chave param para descrever cada argumento para a função. Finalmente, a palavra-chave retorna descreve o valor retornado pela função.

Quando preenchido, o comentário de Doxygen para getAccounts () pode aparecer da seguinte maneira:

/ ** quick getAccounts - entradas de 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 objeto de contagem * Savings ou Checking e adiciona-o à * lista de contas. Um X encerra a entrada. Qualquer outra entrada * é assumida como um depósito (números maiores que * 0) ou uma retirada (números menores que 0). * * lista accList param e a lista de conta * objetos criados por getAccounts () * return void * / void getAccounts (lista & accList) {

Você também pode adicionar um comentário Doxygen na mesma linha. Isso é usado com mais freqüência ao comentar membros de dados. Coloque o cursor no final da linha e selecione DoxyBlocks → Line Comment ou pressione Ctrl + Alt + L. Agora preencha uma descrição do membro de dados. O resultado aparece como no exemplo a seguir, também extraído do Budget5:

duplo saldo; / ** 

Gerando documentação Doxygen
O Doxygen pode gerar documentação em vários formatos diferentes, embora alguns (como HTML compilado) exigem downloads adicionais. O formato HTML é particularmente conveniente, pois requer nada mais do que um navegador para visualizar.
O padrão é HTML, mas se você deseja alterar o formato, selecione DoxyBlocks → Open Preferences, selecione a aba Doxyfile Defaults 2. Nesta janela, você pode selecionar todos os diferentes formatos que deseja gerar.
Antes de extrair a documentação pela primeira vez, você provavelmente quer selecionar algumas outras opções. Selecione DoxyBlocks → Open Preferences e, em seguida, selecione a aba Doxyfile Defaults. Verifique se a caixa Extrair tudo está marcada. Em seguida, selecione a aba Doxyfile Defaults 2 e marque a caixa de seleção Class_Diagrams. Agora selecione a guia Geral e marque a caixa Executar HTML após compilação. Clique em OK, e você terminou. (Você não precisará fazer isso de novo como as opções são salvas em um arquivo chamado doxyfile.)
Selecione DoxyBlocks → Extrair documentação para gerar e visualizar a documentação. Após um intervalo bastante curto, o Doxygen abre seu navegador favorito com documentação como a mostrada na figura a seguir.
O Doxygen não é muito amigável quando se trata de erros de entrada. Às vezes, o Doxygen acaba de gerar documentação em algum momento da sua fonte sem motivo óbvio.Verifique o doxygen. arquivo de log contido no mesmo diretório que o arquivo doxy para quaisquer erros que possam ter ocorrido durante a extração.
A seguinte imagem mostra o navegador do projeto na janela da esquerda que permite ao usuário navegar dentro da documentação do projeto. À direita, a função getAccounts () foi selecionada para obter uma descrição mais detalhada. A breve descrição aparece na primeira linha, seguida da descrição detalhada, dos parâmetros e do valor de retorno:

A documentação da classe é igualmente completa, conforme mostrado pelo seguinte trecho de código.
/ ** classe Conta * abre uma conta bancária abstrata. * detalhes Esta classe abstrata incorpora * propertiescommon para ambos os tipos de conta: * Verificação e Poupança. No entanto, está faltando o * conceito de retirada (), que é diferente * entre os dois * / classe Conta {

A documentação para Conta é mostrada aqui:

Observe a descrição que aparece sob o classe Conta . Esta é a breve descrição. Ao clicar em Mais irá levá-lo para a descrição detalhada. Observe também a representação gráfica do relacionamento de herança entre Conta , suas classes pai e suas classes de crianças.