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á!