Make your own free website on Tripod.com

Documentando as classes com DOxygen

A criação de uma documentação da API do sistema pode parecer redundância, pois todas as classes do sistema foram devidamente documentadas quando foram criadas no Umbrello. Porém nem sempre o usuário tem o Umbrello instalado para ver essa documentação. É muito mais provavel que ele tenha um navegador ou um leitor de arquivos PDF instalado em seu computador.

Um outro ponto é que no momento da implementação, pode surgir a necessidade de explicar o motivo de um parâmetro ter tal formato, ou como será em detalhes o funcionamento da classe. Esse tipo de documentação geralmente é feito no próprio arquivo fonte e assim o próprio arquivo deve ser aberto para ver tal documentação.

Para evitar abrir os fontes, existem ferramentas como o KDoc e DOxygen que conseguem ler esses comentários e gera, assim como o DocBook, documentos em vários formatos para facilitar o acesso a essa documentação. Além da documentação escrita, no caso do DOxygen, também é gerada a hierarquia das classes e, na documentação de cada classe, é mostrado um pequeno diagrama de classes mostrando onde a classe está na hierarquia.

Entre as duas ferramentas, foi escolhido o DOxygen. O KDevelop conhece tanto o KDoc como o DOxygen e consegue executar qualquer uma delas gerando a documentação das classes. Como padrão o KDevelop usa o DOxygen, fato que influenciou bastante na sua escolha. Outro motivo que influiu na escolha foi que o KDE usa o DOxygen para documentar sua API.

Portanto, para gerar a documentação da API do sistema, deve-se pedir para o KDevelop rodar rodar o DOxygen. Ao rodar o DOxygen, serão criados subdiretórios adicionais dentro do diretório onde estão os arquivos fontes do sistema. Dentro desses subdiretórios, o DOxygen coloca os arquivos gerados a partir dos arquivos fontes do projeto. Depois, é só disponibilizar esses arquivos para que o futuro colaborador do sistema não precise nem abrir os arquivos fontes para aprender como trabalham as classes do sistema.

Mais informações sobre o DOxygen, pode ser obtida a partir da leitura de [DOXYGEN].

/**
 * \brief Manipula as formas de pagamento
 *
 * Esta classe permite ao usu�io manipular as formas
 * de pagamento que ser� aceitas pelo sistema. Ela
 * apresenta uma lista com as formas j�cadastradas e
 * permite ao usu�io incluir, alterar e excluir formas
 * de pagamento do banco de dados.
 *
 * Ela �uma subclasse de QListaFormaPagto, que �a
 * classe de interface gerada pelo Designer.
 *
 * \author Anderson Pereira Ataides
 **/

Figura 2. Trecho de documentação no estilo DOxygen