quarta-feira, julho 02, 2008

Usando o Doxygen - parte 1

Venho há alguns anos usando o Doxygen para documentar programas desenvolvidos em C e gostaria de compartilhar a minha experiência.

Embora na maioria dos casos os programas fossem para hardwares embarcados, uso Doxygen sob o Windows, gerando a documentação em formato CHM.

O que é o Doxygen?

Tanto a Wikipedia como meu amigo Caloni descrevem de forma bem completa o que é o Doxygen.

Resumindo bastante, o Doxygen é um programa que gera a documentação de um programa a partir da analise dos fontes de um programa escrito em C (ou linguagens derivadas como C++, Java e C#). Nesta análise são reconhecidas declarações de estruturas de dados e funções e comentários feitos com uma sintaxe especial.

Porque usar o Doxygen?

Muitas vezes é necessário ter uma documentação externa ao fonte. Se esta documentação não for gerada de forma automática, é necessário manter sincronizadas três coisas: o código, os comentários e a documentação. Com o Doxygen basta manter sincronizados os dois primeiros, a documentação será gerada diretamente a partir deles.

Por que gerar CHM? Aliás, o que é um arquivo CHM?

Um arquivo CHM (Compiled HTML Help) é um arquivo de ajuda em formato proprietário da Microsoft, gerado a partir de páginas HTML. Maiores detalhes podem ser vistos na Wikipedia.

A saída nativa do Doxygen é HTML. Entretanto o resultado é um número muito grande de arquivos. Transformando estes arquivos em um arquivo CHM ficamos com um único arquivo e ganhamos recursos de busca e índice. Além disso, o arquivo CHM compacta as páginas de forma bem eficaz.

Nem tudo é perfeito. Como dito, o formato CHM é proprietário e não existe muito suporte a ele fora da plataforma Windows. Outra desvantagem é que o uso de páginas HTML apresentadas através do engine do IE oferece um certo risco de segurança. Por este motivo, o Outlook bloqueia arquivos CHM, não é possível visualizar o conteúdo de um arquivo CHM que está em uma unidade de rede e a Microsoft abandonou os planos de evoluir com o formato.

O que eu preciso para usar o Doxygen e gerar arquivos CHM?

Você precisa instalar o Doxygen, que pode ser baixado do site oficial (aqui).Oo mais simples é baixar e executar o programa de setup para o Windows.

Você precisa baixar e instalar tb o Microsoft Help Workshop do site MSDN (aqui ou aqui)

Por último, você deve utilizar uma formatação especial nos comentários do seu programa. No próximo post vou apresentar a formatação que costumo utilizar. Até lá!

Nenhum comentário: