Documentando Código com Doxygen

Padrão

Doxygen é um sistema de documentação C++, C, Java, Python, IDL (CORBA e variações da Microsoft), Fortran, VHDL, PHP, C# e algumas extensões de D. Bastante coisa, não? Ele é uma ferramenta open-source para geração de documentação e referências de código. A documentação é escrita através de marcações dentro do próprio código-fonte.

Ele pode ajudar de 3 maneiras:

  • ele pode gerar uma documentação online para o navegador (em HTML) e/ou referência offline (em Latex) a partir de um conjunto de códigos documentados. Também há suporte para gerar saída em RTF (Word), PostScript, PDF com links, HTML compactado e man pages do Linux. A documentação é extraída diretamente dos códigos;
  • Você pode também configurar o Doxygen para extrair a estrutura do código com base em arquivos não documentados, de forma a poder visualizar relações entre os vários elementos, o que inclui gráficos de dependência, diagramas de herança e diagramas colaborativos, todos gerados automaticamente;
  • E pode, ainda, gerar documentação padrão.

Altamente portável, roda em Linux, Windows e Mac OS X. Bastante interessante, não?

Mas como faço pra documentar o código?

A sintaxe do Doxygen segue basicamente dois estilos: baseado em Javadoc e baseado em Qt. O estilo Javadoc consiste em um bloco de comentário estilo C começando com dois *, dessa forma:

/**
 * ...texto...
 */

Já a forma em estilo Qt consiste em adicionar uma ! logo após a abertura do comentário:

/*!
 * ...texto...
 */

Existem também outras formas de sintaxe, porém menos utilizadas que estas. Todas elas podem ser encontradas no manual do Doxygen.

Estes blocos de comentários são complementados com o uso de parâmetros que fornecerão os dados necessários para a ferramenta montar a documentação. Vejamos o exemplo:

Usando o estilo Javadoc
/** @brief Descrição breve.
 *         Continuando a descrição breve.
 *
 *  Descrição detalhada começa aqui.
 */

Usando o estilo Qt
/*! \brief Descrição breve.
 *         Continuando a descrição breve.
 *
 *  Descrição detalhada começa aqui.
 */

O Doxygen possui várias tags para formatação da documentação, de forma a possibilitar, de fato, a construção de uma documentação bastante robusta. No exemplo, temos a tag brief que fornece uma breve descrição do elemento a ser documentado.

A seguir, vamos ver uma classe documentada utilizando o Doxygen tanto no estilo Javadoc quanto no estilo Qt.

/**
 *  Uma classe de teste. Uma descrição mais elaborada da classe.
 */

class Teste
{
  public:

    /**
     * Uma enumeração.
     * Descrição mais detalhada da enumeração.
     */

    enum TEnum {
          TVal1, /**< Valor enumerável TVal1. */
          TVal2, /**< Valor enumerável TVal2. */
          TVal3  /**< Valor enumerável TVal3. */
         }
       *ptrEnum, /**< Ponteiro da enumeração. Detalhes. */
       varEnum;  /**< Variável da enumeração. Detalhes. */

      /**
       * Um construtor.
       * Descrição mais elaborada do construtor.
       */
      Teste();

      /**
       * Um destrutor.
       * Descrição mais elaborada do destrutor.
       */
     ~Teste();

      /**
       * Um membro normal com dois argumentos e retornando um valor inteiro.
       * @param a um argumento inteiro.
       * @param s um ponteiro para caractere constante.
       * @see Teste()
       * @see ~Teste()
       * @see meTesteTambem()
       * @see varPublica()
       * @return Os resultados do teste
       */
       int meTeste(int a,const char *s);

      /**
       * Um membro puramente virtual.
       * @see testMe()
       * @param c1 o primeiro argumento.
       * @param c2 o segundo argumento.
       */
       virtual void meTesteTambem(char c1,char c2) = 0;

      /**
       * Uma variável pública.
       * Detalhes.
       */
       int varPublica;

      /**
       * Uma variável função.
       * Detalhes.
       */
       int (*handler)(int a,int b);
};

 

//!  Uma classe de teste.
/*!
  Uma descrição mais elaborada da classe.
*/

class Teste
{
  public:

    //! Uma enumeração.
    /*! Descrição mais detalhada da enumeração. */
    enum TEnum {
                 TVal1, /*!< Valor enumerável TVal1. */
                 TVal2, /*!< Valor enumerável TVal2. */
                 TVal3  /*!< Valor enumerável TVal3. */
               }
         //! Ponteiro da enumeração.
         /*! Detalhes. */
         *ptrEnum,
         //! Variável da enumeração.
         /*! Detalhes. */
         varEnum;

    //! Um construtor.
    /*!
      Descrição mais elaborada do construtor.
    */
    Teste();

    //! Um destrutor.
    /*!
      Descrição mais elaborada do destrutor.
    */
   ~Teste();

    //! Um membro normal com dois argumentos e retornando um valor inteiro.
    /*!
      \param a um argumento inteiro.
      \param s um ponteiro para caractere constante.
      \return Os resultados do teste
      \sa Teste(), ~Teste(), meTesteTambem() and varPublica()
    */
    int meTeste(int a,const char *s);

    //! Um membro puramente virtual.
    /*!
      \sa testMe()
      \param c1 o primeiro argumento.
      \param c2 o segundo argumento.
    */
    virtual void meTesteTambem(char c1,char c2) = 0;

    //! Uma variável pública.
    /*!
      Detalhes.
    */
    int varPublica;

    //! Uma variável função.
    /*!
      Detalhes.
    */
    int (*handler)(int a,int b);
};

Gerando a Documentação

Bom, o primeiro passo é baixar o Doxygen. No Windows, você pode baixar do site oficial mesmo, aqui. No Linux você pode baixar do site oficial, ou dos repositórios da sua distribuição (a maioria tem).

No caso especial do Windows, ele vem com o Doxywizard. Com ele, é bem fácil configurar o projeto.

No caso do Linux, o processo é um pouco mais trabalhoso, já que temos que fazer o processo de configuração manualmente. Primeiramente, navegue até a pasta onde os códigos ou o projeto está. Chegando lá, digite:

doxygen -g

Com isso, um arquivo chamado Doxygen será gerado na pasta atual. A sintaxe deste arquivo é bastante similar à sintaxe de um Makefile comum. Após a configuração dos parâmetros, basta salvar e executar:

doxygen Doxygen

Neste link você obtém mais informações sobre as configurações do arquivo.

Assim, teremos algo parecido com isso ao gerarmos a documentação do código-fonte de exemplo:

Bacana, não? Aqui você encontra um exemplo de documentação de um projeto real gerada com o Doxygen.

Espero que seja útil a vocês, assim como foi pra mim! 😀

Até a próxima!

  • Suellen

    Muito Legal =)

  • Oi Rafael,

    estou tentando gerar documentação com o doxgen mas os caracteres especiais, como: ç, ~, ´, etc… não estão sendo decodificados bem para o HTML.

    Você teve algum problema desses?

    Abraço!

    • 123d4

      deixa em utf-8 que isso n ocorrerá