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). No fundo da janela Seleccione a opção Optimize output for C.
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. Verifique se as opções seleccionadas são as seguintes:
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: Para terminar a configuração carregue no botão OK.
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. Abra o ficheiro index.html para navegar na documentação.
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.