Documentação de código com Doxygen

Programador gosta de programar. Escrever documentação, fazer desenho, gerar gráfico, tudo firula que muitos não gostam. E ainda tem um monte de programador que mal comenta código fonte. Mas tem uma maneira muito bacana de fazer a documentação de código a partir dos comentários, usando o Doxygen.

O que é Doxygen?

O Doxygen é um gerador de documentação de código para diversas linguagens como C/C++, Qt, Java, Objective-C, Python, Fortran, IDL, PHP, C# etc. Usando Doxygen, podemos gerar uma documentação de qualidade que inclui gráficos de relacionamento e a saída pode ter diversos formatos.

O Doxygen para Linux não tem GUI por padrão, mas há um front-end bacana; o doxywizard. Para Windows e Mac o Doxygen inclui a interface gráfica. Downloads podem ser feitos nesse link.

Para Linux, use o repositório de sua distribuição. Para distribuições baseadas em Debian:

sudo apt-get install doxygen doxywizard

Como usar o Doxygen?

Seu foco deve ser inicialmente no código. Os comentários serão a referência para o Doxygen gerar a documentação. Costumo usar o formato de comentários do Qt para C++. No caso, os comentários podem ser:

/*! comentário de múltiplas linhas.
continua nessa linha...
*/

//! Comentário de uma linha
//! que pode continuar assim também
/// ou assim.

Os comentários farão referência ao que vem em seguida, mas também podemos colocar os comentários diante de um elemento. Por exemplo:

String minha_variavel; //!< String do Arduino

Também podemos documentar parâmetros de função, fazendo desse jeito:

/*! Um método no Qt (ou qualquer outra coisa em C++) com dois parâmetros, sendo:
     *  \param a uma string qualquer.
     *  \param b um inteiro qualquer.
     *  \return void Sem retorno.
    */
    void MetodoDois(QString a, int b);

Podemos também documentar o parâmetro inline, fazendo dessa maneira:

void doisTres(int valor /*!< [in] vai virar outro valor*/);

E podemos incluir fórmulas com LaTex, usando f$ para início e fim de fórmula:

/*! O resultado desse método é sempre \f$\fraq{\sqrt{valor}}{valor^3}\f$. Ou não.
 *  Lembrando que @param valor deve ser um inteiro (ou não).*/
    void doisTres(int valor /*!< [in] vai virar outro valor*/);

Fiz um código não sem implementações funcionais pra exemplificar a documentação. Os comentários podem ir no header, na implementação ou em ambos. No caso, coloquei apenas no header, que ficou assim:

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QMap>
#include <QDebug>

/*! \brief Descrição do programa
 *  Esse programa é um exemplo de como documentar código com doxygen.
*/

QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }
QT_END_NAMESPACE

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

    /*! Recebe uma string, passa para maiúscula e coloca no array
    */
    void MetodoSimples(QString teste /*!< [in] documenta parâmetro de entrada. */);

    /*! Um método com dois parâmetros, sendo:
     *  \param a uma string qualquer.
     *  \param b um inteiro qualquer.
     *  \return void Sem retorno.
    */
    void MetodoDois(QString a, int b);

    /*Alguns tipos específicos precisam ser explicitados para documentá-los:
    \struct    - para documentar um struct
    \union     - para documentar um union
    \enum      - para documentar um enumerador
    \fn        - para documentar uma função
    \var       - para documentar o valor de uma variável, definição de tipo ou enumerador
    \def       - para documentar um define
    \typedef   - para documentar a definição de um tipo
    \file      - para documentar um arquivo
    \namespace - para documentar um namespace
    @ pode ser usado, invés de \. Ex.: @enum
    */

    //L A T E X
    /*! O resultado desse método é sempre \f$\fraq{\sqrt{valor}}{valor^3}\f$. Ou não.
     *  Lembrando que @param valor deve ser um inteiro (ou não).*/
    void doisTres(int valor /*!< [in] vai virar outro valor*/);

private:
    Ui::MainWindow *ui;

    QStringList arrayDeStrings; /*!< Guarda um array de strings. */
    int counter;                //!< guarda o número de elementos no array.
    QMap <int,QString>   ambos; ///< com 3 barras também funciona.
};
#endif // MAINWINDOW_H

Como gerar a documentação com Doxygen

Agora abra a interface do Doxygen e preencha os campos como necessário; nome de projeto, logo, versão, diretório do código fonte e onde a documentação deve ser gerada:

Clique em Next até Diagrams. Nesse menu você pode optar por gerar gráficos e nesse caso será necessário instalar um gerador ou usar o gerador interno. Eu costumo instalar o GraphViz, mas fica a seu critério. Se possível, experimente. Quando for para a aba Run, bastará clicar em Run doxygen. Será criado um diretório com a documentação nos formatos escolhidos. O formato HTML é bacana para navegação, mas vou colocar só prints aqui, no vídeo que farei posteriormente mostro em detalhes.

Como fiz algo simples, o gráfico ficou simples. Mas tenho um projeto bem mais elaborado que está no github. O gráfico desse outro projeto "apenas" da janela principal ficou assim:

E os gráficos são clicáveis, permitindo navegar pelo relacionamento. A documentação pode ser gerada com frames também. Esse projeto tem diversas classes e é bastante complexo, por isso a documentação fica bem bacana:

Precisa fazer a documentação de código? Não sofra mais por isso, com auxílio do Doxygen!

Não deixe de inscrever-se em nosso canal no Youtube para ver o vídeo desse artigo e outros mais!