Documentando Código com Doxygen

Doxygen é um sistema de documentação C++, C, Java, Python, IDL (CORBA e variações da Microsoft), Fortran, VHDL, PHP, C# e algumas extensões de D. Bastante coisa, não? Ele é uma ferramenta open-source para geração de documentação e referências de código. A documentação é escrita através de marcações dentro do próprio código-fonte.

Ele pode ajudar de 3 maneiras:

  • ele 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;
  • Você pode também 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;
  • E pode, ainda, gerar documentação padrão.

Altamente portável, roda em Linux, Windows e Mac OS X. Bastante interessante, não?

Mas como faço pra documentar o código?

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:

Já a forma em estilo Qt consiste em adicionar uma ! logo após a abertura do comentário:

Existem também outras formas de sintaxe, porém menos utilizadas que estas. Todas elas podem ser encontradas no manual do Doxygen.

Estes 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:

O Doxygen possui várias tags para formatação da documentação, de forma a possibilitar, de fato, 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.

A seguir, vamos ver uma classe documentada utilizando o Doxygen tanto no estilo Javadoc quanto no estilo Qt.

 

Gerando a Documentação

Bom, o primeiro passo é baixar o Doxygen. No Windows, você pode baixar do site oficial mesmo, aqui. No Linux você pode baixar do site oficial, ou dos repositórios da sua distribuição (a maioria tem).

No caso especial do Windows, ele vem com o Doxywizard. Com ele, é bem fácil configurar o projeto.

No caso do Linux, o processo é um pouco mais trabalhoso, já que temos que fazer o processo de configuração manualmente. Primeiramente, navegue até a pasta onde os códigos ou o projeto está. Chegando lá, digite:

Com isso, um arquivo chamado Doxygen será gerado na pasta atual. A sintaxe deste arquivo é bastante similar à sintaxe de um Makefile comum. Após a configuração dos parâmetros, basta salvar e executar:

Neste link você obtém mais informações sobre as configurações do arquivo.

Assim, teremos algo parecido com isso ao gerarmos a documentação do código-fonte de exemplo:

Bacana, não? Aqui você encontra um exemplo de documentação de um projeto real gerada com o Doxygen.

Espero que seja útil a vocês, assim como foi pra mim! 😀

Até a próxima!