Guia Doxygen Emanuel Filipe Galdino Alves (emanuel.alves@ee.ufcg.edu.br) O Doxygen é um programa que gera a documentação de um software a partir da análise do código escrito em C, C++, C#, Java, Python, Fortran, VHDL, PHP e algumas extensões de D. A ferramenta Doxygen é open-source e sua documentação é gerada a partir de estruturas de dados, funções e comentários do código-fonte feitos com uma sintaxe especial. O Doxygen pode gerar uma documentação online para o navegador (em HTML) e/ou referência offline (em Latex) a partir de um conjunto de códigos documentados. Também há suporte para gerar saída em RTF (Word), PostScript, PDF com links, HTML compactado e man pages do Linux. A documentação é extraída diretamente dos códigos. Também pode-se configurar o Doxygen para extrair a estrutura do código com base em arquivos não documentados, de forma a poder visualizar relações entre os vários elementos, o que inclui gráficos de dependência, diagramas de herança e diagramas colaborativos, todos gerados automaticamente. Como documentar o código com Doxygen A documentação de qualquer código fonte começa na forma de escrever os comentários necessários para deixar o código o mais auto explicável possível tanto para uma futura manutenção do código como para os futuros programadores que poderão entrar no meio do projeto. A sintaxe do Doxygen segue basicamente dois estilos: baseado em Javadoc e baseado em Qt. O estilo Javadoc consiste em um bloco de comentário estilo C começando com dois *, dessa forma: /** *...texto... Já a forma em estilo Qt consiste em adicionar uma! logo após a abertura do comentário: /*! *...texto... Outras formas de sintaxes são encontradas no manual do Doxygen: http://www.stack.nl/~dimitri/doxygen/manual/index.html Os blocos de comentários são complementados com o uso de parâmetros que fornecerão os dados necessários para a ferramenta montar a documentação. Vejamos o exemplo: 4 5 Usando o estilo Javadoc /** @brief Descrição breve. * Continuando a descrição breve. * * Descrição detalhada começa aqui.
6 7 8 9 0 Usando o estilo Qt /*! \brief Descrição breve. * Continuando a descrição breve. * * Descrição detalhada começa aqui. O Doxygen possui várias tags para formatação da documentação, de forma a possibilitar, a construção de uma documentação bastante robusta. No exemplo, temos a tag brief que fornece uma breve descrição do elemento a ser documentado. Como gerar a Documentação Primeiramente, é necessário baixar o Doxygen no site oficial: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc A instalação do programa é bastante simples. No Windows, usa a interface Doxyward para configuração do projeto. Segue-se os passos para geração da documentação.. Primeira tela que será exibida ao iniciar o Doxyward Figura 0. Deve-se fazer as ações a seguir indicadas na figura 0 e clicar next : a. Seleciona onde está o executável Doxyward; b. Escolhe o nome do projeto; c. Seleciona o diretório onde está salva o código; d. Seleciona essa caixa para que o Doxygen possa ter acesso a todas as subpastas do software que se deseja documentar; e. Seleciona a pasta onde a documentação será salva.
Figura 0 Figura 0
4. Deve-se selecionar os campos indicados na figura 04 e clicar next. Figura 04 4. Na figura 05, seleciona-se o tipo de arquivo de saída que será gerado para documentação. Foi escolhido arquivo do tipo HTML. Clica-se em next. Figura 05
5 5. O tópico Diagrams já está configurado corretamente, sendo assim, clica-se em next e em Expert em seguida. Na aba Expert clica no tópico Output e seleciona *.cpp no campo FILE_PATTERNS, já que o software a ser documentado foi escrito em linguagem C++. Figura 06 6. No tópico Source Browser seleciona a caixa INLINE_SOURCES e clica na aba Run. Figura 07
6 7. Na aba Run, clica-se em Run doxygen para gerar a documentação e em Show HTML output para ver a documentação gerada aberta no navegador. Figura 08 8. Por fim, se tem a documentação gerada pelo Doxygen. Figura 09