Documentando Código com
Doxygen
Boa tarde a todos, este é um tutorial que "peguei emprestado" do blog do Rafael Toledo (
link), achei muito interessante publica-lo/dissemina-lo pela net, pois estava com a mesma dúvida e me ajudou muuuito!!
Eu particularmente já usava a descrição de código no estilo:
/*
* ...texto...
*/
mas não sabia que poderia ser utilizado para gerar documentos.
Bom, segue então o tutorial, bom proveito a todos.
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
eman 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 emQt. O estilo Javadoc consiste em um bloco de comentário estilo
C começando com dois *, dessa forma:
|
1
2
3
|
/**
*
...texto...
*/
|
Já a forma em
estilo Qt consiste em adicionar uma ! logo após a
abertura do comentário:
|
1
2
3
|
/*!
*
...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:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
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 tagbrief que fornece uma breve descrição do elemento
a ser documentado.
A seguir, vamos ver
uma classe documentada utilizando o Doxygen tanto
no estiloJavadoc quanto no estilo Qt.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
|
/**
* 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);
};
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
//! 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:
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:
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!
