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.

5
Deixe um comentário

avatar
 
2 Comment threads
3 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
3 Comment authors
EDINALDO SERRA CARDOSO JUNIORRafael Alves DiasMarcelo Jo Recent comment authors
  Notificações  
recentes antigos mais votados
Notificar
EDINALDO SERRA CARDOSO JUNIOR
Visitante
EDINALDO SERRA CARDOSO JUNIOR

Marcelo, você conhece alguma outra ferramenta que faça documentação de código em linguagem C? É pra um trabalho da faculdade do curso de Ciência da Computação na disciplina de Engenharia de Software 1.

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