Documentação de código – 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:

Os Melhores Treinamentos sobre Sistemas embarcados e IoT

Cursos com professores qualificados para acelerar sua carreira e projetos

MATRÍCULE-SE AGORA

/**
 * @file  Template.c
 * @brief Arquivo de exemplo - Doxygen
 *
 * @warning Documentar código é muito importante.
 * @todo Lista do que implementar
 * @bug Lista de bugs conhecidos
 * @copyright Embarcados - sua fonte de informações sobre Sistemas Embarcados
*/

#include "exemplo.h"

/*******************************************************************
*   CONFIGS
*******************************************************************/

/*******************************************************************
*   DEFINES
*******************************************************************/

/*******************************************************************
*   TYPEDEFS
*******************************************************************/
typedef unsigned char   uint8_t;
typedef unsigned short  uint16_t;

/*******************************************************************
*   GLOBAL VARIABLES
*******************************************************************/

/*******************************************************************
*   CONSTANTS
*******************************************************************/

/*******************************************************************
*   LOCAL PROTOTYPES
*******************************************************************/
/**
 * @fn EEPROM_Write(uint16_t ui16_Address, uint8_t *pBuffer, uint16_t ui16_Len)
 * @brief Write data into EEPROM
 * @param ui16_Address - First address to be read
 * @param pBuffer - Pointer to buffer to return data read
 * @param ui16_Len - How many bytes to read
 * @return Byte quantity written
 * @remarks If function try to write into an invalid address, it will finish and
 * return how many bytes it could write
*/
uint16_t EEPROM_Write(uint16_t ui16_Address, uint8_t *pBuffer, uint16_t ui16_Len);


/*******************************************************************
*   IMPLEMENTATION
*******************************************************************/
/**
 * Read data from EEPROM
*/
uint16_t EEPROM_Read(uint16_t ui16_Address, uint8_t *pBuffer, uint16_t ui16_Len)
{
    
}

/**
 * Write data into EEPROM
*/
uint16_t EEPROM_Write(uint16_t ui16_Address, uint8_t *pBuffer, uint16_t ui16_Len)
{
    
}

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

sudo apt-get install doxygen doxygen-gui

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

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: [wpdm_asset id=’34’]

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 é https://www.stack.nl/~dimitri/doxygen/.

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