Doxygen

• Versão: 1.3.8
• Data: 25/Ago/2004

vvvvvvvvvvvvvvvvvvvvvv Apesar de ser uma das tarefas de um processo de codificação, a produção de documentação técnica nunca é tão bem vista e encarada quanto a produção de código-fonte. Para aliviar este sintoma existem ferramentas automáticas de geração de documentação técnica, tendo como base (input) o próprio código-fonte.

O Doxygen é uma destas ferramentas, distribuída com licença GPL, que é adequada para utilização com código-fonte em linguagens de programação tais como C/C , Java, ou até mesmo C# e PHP. Além de ser aberta e livre, é uma solução que se distingue de outras soluções idênticas pelo seu suporte a um enorme leque de formatos de documentos: HTML, LateX, PDF, RTF, Postscript, etc. É tão flexível que o próprio Manual de Utilização (User’s Guide) foi gerado através do Doxygen.

O Doxygen é desenvolvido debaixo do Linux e Mac OS X, mas é portado para a grande maioria dos sistemas operativos.

O Doxygen é um sistema de geração automática de documentação técnica a partir do código-fonte. As linguagens reconhecidas pelo sistema são: C/C++, Objective-C, Java, IDL e PHP, C# e D.

O Doxygen é útil para:

1. gerar documentação online (em HTML) para ser acedida através de uma rede TCP/IP;
2. gerar documentação offline (em PDF, RTF, PostScript, …);
3. extrair informação directamente a partir do código-fonte, com ou sem comentários;
4. visualizar as relações entre as entidades, por exemplo através de grafos de dependência ou diagramas de herança.
5. gerar documentação não técnica, se bem que é um “abuso” das funcionalidades do Doyxgen.

Esta extracção automática de informação a partir do código-fonte é bastante útil para se manter a documentação técnica consistente e sempre actual. Mesmo sem comentários, e como reconhece a linguagem de programação, consegue gerar informação sobre as entidades e as suas interligações, que é muito importante na análise de grandes projectos ou de aplicações “legadas” (legacy).

Antes de mais1), é importante saber se realmente é necessário documentar o código-fonte. Caso a resposta seja afirmativa, é preciso perceber as vantagens e desvantagens da aplicação de ferramentas automáticas de geração de documentação técnica. Só então fica claro o porquê de se usar o Doxygen numa equipa de produção/manutenção de software.

Existem diversas razões para se documentar o código-fonte:

• Porque a empresa requer documentação, de acordo com normas em vigor.
• Porque é preciso entender o código, mesmo após imenso tempo sem ter realizado processos de codificação.
• Porque é preciso responder eficazmente aos restantes membros da equipa, sobre dúvidas ou questões técnicas relacionadas com o código-fonte.
• Porque é preciso transferir o conhecimento e entendimento sobre o sistema aos restantes membros da equipa, novos ou antigos.

É possível não documentar o código-fonte, especialmente quando a equipa é composta por poucos elementos ou quando se trabalha sozinho. No entanto, após o projecto crescer substancialmente, quer em tamanho quer no número de recursos alocados, cedo se começa a identificar a necessidade de existir alguma documentação, seja informal ou mesmo até formal, sobre o código-fonte. Naturalmente, quanto mais cedo se começar a documentar, mais fácil será manter a documentação correcta. E com o suporte de uma ferramenta automática, sempre pronta a ser usada, fica mais simples começar a documentar o código-fonte.

Estas são as vantagens mais comuns na aplicação de uma ferramenta automática de geração de documentação técnica ao código-fonte de um projecto de software:

• A documentação está sempre actualizada.
  É muito mais prático alterar-se um comentário directamente no código-fonte do que abrir um sistema de documentação externo e editar a documentação respectiva sobre a alteração efectuada ao código-fonte.
• Re-utilização dos comentários.
  Após se ter descoberto as virtudes da documentação do código-fonte, o valor dessa documentação duplica.
• Formatação automática.
  Com simples markup, a documentação técnica gerada tem um aspecto profissional, coeso, coerente e consistente.
• Cross-Linking.
  A ligação entre entidades e as suas dependências é automática, sem ser necessário “lutar” de forma “inglória” com sistemas externos de documentação.
• Comentários Inline.
  Nem toda a informação está disponível a partir do código-fonte. Um estilo formal para os comentários inline com o código-fonte implica a aquisição mais rica de meta-informação.

• Documentar o pseudo-código e guardá-lo como documentação.
• Documentar alterações pontuais ao código-fonte, em detrimento da realização de uma documentação a toda a escala, integral, do sistema.
• Documentar código legado, sempre que seja compreendido, durante tarefas de manutenção correctiva ou evolutiva.

• Como associar documentos Wiki às páginas Doxygen, e vice-versa?
  A resposta a esta questão passa a ser uma Best-Practice, e pode recorrer ao uso do mecanismo InterWiki entre o DokuWiki e o Doxygen.

Indicar casos de sucesso, a nível nacional, no uso desta solução.