Documentação de código - Doxygen

doxygen

Tudo na vida há um lado bom e outro nem tanto. Trabalhar com desenvolvimento de software e firmware não seria exceção. Porém isso não significa que documentar código seja algo ruim, mas normalmente, para nós desenvolvedores, o prazer está em escrever código e não documentá-lo.

 

Michael Barr cita em seu livro Embedded C Standard Coding"Programadores não são donos dos códigos que escrevem. Todo software desenvolvido pertence ao empregador ou a algum cliente [...]".

 

Documentar é, portanto, mais do que necessário. É sim uma obrigação por parte de nós programadores! A fim de facilitar esse trabalho, criaram-se ferramentas para automatizar e padronizar todo esse processo. Uma ferramenta gratuita muito usada é o Doxygen.

 

As principais vantagens dessa ferramenta são:

 

  • Pode ser usado em Windows, Linux e Mac OS;
  • Suporta diversas linguagens como: C/C++, Objective-C, C#, PHP, Java, Python, VHDL, entre outros;
  • Cria documentação em HTML, PDF, Unix man pages e vários outros formatos;
  • Permite visualizar dependências entre elementos através de grafos, diagramas de herança e diagramas de colaboração.

 

 

Essa ferramenta, usada em conjunto com um padrão para se escrever código, possibilitaria a documentação automatizada a cada nova release do projeto. A sintaxe é bem simples e, no caso de um programa em C, teríamos como exemplo:

 

 

Em sistemas Linux é necessário instalar o doxygen e sua interface gráfica, o doxygen-gui. No Ubuntu digite:

 

 

A interface gráfica é simples e para gerar a documentação em HTML basta seguir os passos abaixo:

 

photo14

 

Passo 1 - Selecionar o diretório do projeto;

 

Passo 2 - Preencher os 4 tópicos: Project, Mode, Output e Diagrams;

 

  • Em Project, coloque o nome do projeto, selecione o diretório do código fonte e o diretório onde o Doxygen irá salvar a documentação;
  • Em Mode, como nosso exemplo é em C, selecione "Optimize for C or PHP output";
  • Em Output, selecione  "plain HTML";
  • E finalmente em Diagrams selecione "No diagrams".

 

 

Passo 3 - Selecione a aba "Run" e clique em "Run doxygen".

 

Pronto! O download da documentação HTML gerada pode ser feito através do link: Documentação HTML do arquivo Template.c. Abra o arquivo index.html no navegador de preferência.

Diversos exemplos de projetos, como o KDE, podem ser vistos aqui. O site oficial do doxygen é http://www.stack.nl/~dimitri/doxygen/.

 

E você caro leitor, possui o bom hábito de documentar seu código? Quais ferramentas tem usado?

 

NEWSLETTER

Receba os melhores conteúdos sobre sistemas eletrônicos embarcados, dicas, tutoriais e promoções.

Obrigado! Sua inscrição foi um sucesso.

Ops, algo deu errado. Por favor tente novamente.

Licença Creative Commons Esta obra está licenciada com uma Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional.

4
Deixe um comentário

avatar
 
1 Comment threads
3 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
2 Comment authors
Marcelo JoRafael Alves Dias Recent comment authors
  Notificações  
recentes antigos mais votados
Notificar
Rafael Alves Dias
Visitante
Rafael

Marcelo, muito bom estava precisando fazer documentação do firmware e não sabia como fazer...

Vi aqui seu exemplo, mas não consegui fazer... precisa de algum aquivo dentro da pasta do projeto onde está o arquivo .c pra funcionar?

Marcelo Jo
Visitante
Marcelo Jo

E aí Rafael, tudo bom?
Qual problema você está encontrando? Nenhum arquivo é gerado? Alguma mensagem de erro do Doxygen?
A principio você só precisa dizer pro programa onde está o código fonte.

Rafael Alves Dias
Visitante
Rafael

Obrigado pela resposta rápida Marcelo. Peguei esse seu exemplo e copiei em um bloco de notas, e salvei em uma pasta na área de trabalho. Em Project: No step 1: indiquei a pasta que criei (com o aquivo .c apenas) Em Source code directory: indiquei a mesma pasta Em Destination directory: indiquei a mesma pasta Mode: Selecionei a opção: optimize for C or PHP output Output: Selecionei a opção: Plain HTML Diagrams: Selecionei a opção: No diagrams E depois cliquei em run para gerar a pagina. A página é gerada mas apenas com as informações que coloquei na aba project,… Leia mais »

Rafael Alves Dias
Visitante
Rafael

Marcelo o meu erro estava na extensão do arquivo. Achei que havia colocado .c ou .h, mas estava como txt e por isso não funcionou, bastou trocar a extensão do arquivo para funcionar normalmente. Obrigado pela atenção