Programação 2008/2009
MEEC - MEAer
Doxygen
O Doxygen é um sistema que a partir dos comentários de um programa consegue gerar a documentação (em html por exemplo) desse programa.
O utilizador deverá seguir umas regras simples ao comentar o código (funções, definição de tipos, ...), depois é suficiente o utilizador invocar o Doxygen para gerar a documentação do programa.
Neste documento é descrito como configurar o KDevelop para se usar o Doxygen, como invocar o Doxygen dentro do KDevelop e como deverão ser formatados os comentários.
Configuração do KDevelop
Seleccione o menu Project -> Project Options.
Abrir-se-á a janela de configuração do projecto. Seleccione a Opção Doxygen (do lado esquerdo da janela).
Seleccione a paleta Build (no cimo da janela).
As 5 primeiras opções deverão ser seleccionada. Garanta que as outras opções estão como na seguinte figura.
Seleccione a paleta Source Browser.
Como só queremos gerara documentação em formato html, devemos garantir que essa opção está seleccionada.
Escolha a paleta HTML e verifique que a opção Generate HTML está seleccionada.
Devemos seleccionar agora as paletas LaTex, RTF e XML para garantir que não será gerada documentação nesse formato:
Falta configurar a geração de gráficos com as relações entre os diversos ficheiros, tipos e funções.
Seleccione a paleta Dot e verifique que estão seleccionados as seguintes opções:
Execução do Doxygen
Seleccione o menu Build -> Build API Documentation.
Sempre que modificar o código ou os seus comentário deverá repetir o comando anterior. Para ver a documentação use um gestor de ficheiros (por exemplo o Dolphin) e vá à directoria do projecto. Aí dentro há uma outra directoria chamada html.
Comentários
Nos caso dos programas escritos em C o Doxygen só gera documentação para as funções estruturas e defines.
Para que o Doxygen gere a documentação é necessário que os comentários no código (ficheiro .c e .h) sigam um determinado formato. Para um comentário ser processado pelo Doxygen é necessário que comece por /** . Para cada tipo de elemento a documentar assim o formato dos comentários é diferente.
#define
Para gerar documentação de um define é necessário usar (dentro do comentário) o comando \def seguido da constante definida. Na linhas seguintes deverá aparecer a documentação da constante:
/**
@def PI
@brief Dedinicao da constante PI Esta definicao e necessaria porque
o math.h não contem a definicao da constante PI */
#define PI 3.141595
O comando \brief permite escrever uma pequena descrição da constante. Nos parágrafos seguintes deverá aparecera uma descrição mais pormenorizada dos objectivos e usos da constante.
Estruturas
Para documentar a definição de um novo tipo estrutura (typedef struct) basta inserir os comando do Doxygen no comentário imediatamente anterior:
/**
@brief tipo imaginario
tipo usado para representar valores numericos imaginario (compostos por uma parte real e outra imaginaria)
*/
typedef struct s_imag{
/** @brief parte imaginaria */ float p_imag;
float p_real; /** @var p_real parte real */
}imaginario;
Se o comentário imediatamente anterior ao typedef struct começar por /** o Doxygen associa-o automaticamente ao typedef. Dentro desse comentário podemos usar o comando @brief seguido de uma breve descrição do novo tipo, seguido de uma descrição mais pormenorizada.
Para comentar os membro internos à estrutura devemos usar um comentário imediatamente antes da definição (como exemplificado no caso do p_imag) ou ,se o comentário ocorrer
após a declaração (como na p_real), informar qual o membro que se está a comentar usando o comando @var seguido do nome do membro.
Funções
Para documentar as declaração ou implementação das funções basta inserir um comentário (começado por /**) antes dessas funções. O Doxygen automaticamente associa-o à função que ocorre a seguir.
/**
@brief Funcao principal
Esta funcao escreve no ecran a string "Hello, world" e sai. @param argc numero de parametros que ocorrem no argv
@param argv[] vector com os parametros escritos na linha de comando pelo utilizador
@return valor indicador de erro ou sucesso ( */
int main(int argc, char *argv[]) {
printf("Hello, world!\n"); return EXIT_SUCCESS;
}
O comando @param é usado para documentar os parâmetros de uma função. O comando @param é seguido do nome do parâmetro e de uma descrição do mesmo.
O comando @return é seguido da descrição dos valores retornados pela função.
Caso o cabeçalho de uma função ocorra separado da sua implementação (por exemplo no início do ficheiro .c ou num ficheiro .h), deve-se usar o comando @brief no comentário Doxygen que precede o cabeçalho.
