Documentando aplicações em C com o Doxygen

December 31st, 2007 Posted in Tecnologia

O Doxygen é um sistema de documentação para C, C++, java, Python e outras linguagens. Com ele é possível gerar documentação em HTML, RTF, PostScript, PDF e até man pages.

Ele utiliza um arquivo de configuraçao para controlar o processo de documentação, que pode ser gerado apartir do comando: doxygen -g doxygen.conf, o arquivo gerado possui a descrição de todos os campos, aqui serão descritos apenas alguns.

Campos alterados do arquivo de configuração padrão:

# Nome do projeto

PROJECT_NAME = "Nome do Projeto"# Número da versão/revisão do projeto

PROJECT_NUMBER = 0.0.1

# Diretório onde os arquivos gerados serão gravados

OUTPUT_DIRECTORY = /home/daniel/projetos/teste1/doc

# Qual lingua será gerada a documentação, existe o suporte para Português do Brasil.

OUTPUT_LANGUAGE = Brazilian

# Tamanho do TAB, por padrão é 8, eu gosto de 2. Você define da maneira que achar mais conveniente.

TAB_SIZE = 2

# Neste caso a aplicação é em C.

OPTIMIZE_OUTPUT_FOR_C  = YES

# Arquivo de log do doxygen.

WARN_LOGFILE = /home/daniel/projetos/teste1/log/doxygen.log

# Diretório onde está o projeto

INPUT = /home/daniel/projetos/teste1/

# Os tipos de arquivos que serão documentados, é possível colocar mais de uma extensão da seguinte maneira

# FILE_PATTERNS += *.h

FILE_PATTERNS = *.c

# Buscar nas pastas recursivamente.

RECURSIVE = YES

# É possível inserir o código fonte junto da documentação alterando esta TAG para YES.

SOURCE_BROWSER = NO

# Por padrão o doxygen gera documentos HTML, caso não queria gerar os arquivos HTML altere esta TAB para NO

GENERATE_HTML = YES

# Alterando as TAGs a seguir é possível personalizar os arquivos HTML gerados.

# Arquivo de cabeçalho.

HTML_HEADER = header.html

# Arquivo de Rodapé.

HTML_FOOTER = footer.html

# Arquivo com os estilos.

HTML_STYLESHEET = estilo.css

Documentando o código

A maneira de documentar o código para o doxygen é muito parecida com a utilizada pelo JAVADOC. Exemplo:

/**

  @brief Função principal do sistema.

*/

int main(void)

{

  printf("Teste\n");

  return 0;

}

Existem vários comando para serem utilizados na documentação da sua aplicação, irei descrever os mais utilizados. A lista completa está disponível no site do doxygen

@brief - Uma breve descrição da função.
@details - Uma descrição mais detalhada da função.
@author - O nome do autor da função, é possível especificar vários autores.
@return - O que a função retorna.
@retval - Os possíveis valores retornados.
@param variável - As variáveis recebidas pela função.

O exemplo para uma função documentada seria:

/**
  @brief Função que faz o tratamento de um comando do tipo POST.

  @param str String referente ao comando.
  @param socket Socket do cliente.
  @param thread_id  ID da thread.

  @return Status do atendimento da requisição

  @retval 0 Sucesso
  @retval -1  Falha

  @author Daniel Matte Freitas

*/

int trataComandoPost(char *str, int thread_id, int socket)

{

   ……

}

Gerando a documentação

Para gerar a documentação é necessário apenas um comando: doxygen < arquivo >. Exemplo: doxygen doxygen.conf

Um exemplo de documentação gerada pelo doxygen pode ser visto aqui.

Conclusão e considerações

Infelizmente a documentação dos códigos é mal vista pela maioria dos programadores. Confesso que já relutei muito para não documentar meus códigos, mas hoje vejo que é de grande importância. Acredito que o maior motivo para que muitos não documentem seus códigos é o tempo “perdido” para fazer isto, mas hoje existem ferramentas muito interessantes que facilitam este trabalho, como o doxygen. Em poucas linhas dentro do próprio código é possível documentá-lo e depois com um simples comando gerar todo o documento.

O intuito deste documento é apresentar esta ferramenta para documentação de códigos, doxygen, no site é possível fazer o download do mesmo e sua documentação.

  1. One Response to “Documentando aplicações em C com o Doxygen”

  2. By Luizxx on Jan 2, 2008

    Ótimo artigo!
    Realmente o Doxygen facilita muito a vida na hora de documentar as coisas…

Post a Comment