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: 

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?

Website | Veja + conteúdo

Engenheiro eletrônico com 10 anos de experiência em sistemas embarcados, pós graduado em redes de computadores e atualmente cursando mestrado em sistemas de visão por computador na universidade Laval no Canadá. Compartilha seu conhecimento neste portal quando tem tempo livre e quando não está curtindo a vida com sua mulher e os 3 filhos.

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

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

Comentários:
Notificações
Notificar
guest
6 Comentários
recentes
antigos mais votados
Inline Feedbacks
View all comments
Marlon Pedersoli
Marlon
30/01/2020 11:02

Tentei usar o mesmo codigo e com a mesma configuracao mostrada no artigo, mas infelizmente nao aparece nada. Imagino q sejam alguns passos que nao estejam descritos no artigo. Alguém poderia me orientar?

EDINALDO SERRA CARDOSO JUNIOR
EDINALDO SERRA CARDOSO JUNIOR
21/09/2019 22:34

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
Rafael
01/04/2015 09:54

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
Marcelo Jo
Reply to  Rafael
01/04/2015 10:07

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
Rafael
Reply to  Marcelo Jo
01/04/2015 10:23

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
Rafael
Reply to  Rafael
01/04/2015 11:15

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

Talvez você goste:

Séries

Menu