Make your own free website on Tripod.com

Documentação do sistema

Nenhum sistema é realmente bem desenvolvido se não tiver uma documentação que facilite, tanto ao desenvolvedor quanto ao usuário a compreensão e utilização de todas as partes que formam o sistema. Além disso, a forma na qual essa documentação é disponibilizada, também pode ser de fundamental import�cia na "popularização" do sistema.

As ferramentas de modelagem e de implementação escolhidas, facilitam bastante o trabalho "braçal", mas não são tão eficientes para disponibilizar a documentação. Para se tornar um software popular e para atrair o interesse de programadores da comunidade open source, todo o sistema deve ser documentado de modo que o desenvolvedor consiga entender o funcionamento e implementação antes mesmo de ver o código fonte.

Para documentar as classes, os arquivos header foram todos documentados de acordo com as especificações do DOxygen. O DOxygen é um sistema de documentação para programas escritos em C, C++, Java entre outras linguagens. Ele lê os arquivos fonte e gera uma documentação para a API do sistema. Essa documentação pode ser gerada em vários formatos como páginas HTML (Hypertext Markup Language), PDF (Portable Document Format) e RTF (Rich Text Format). Logicamente, os comentários na codificação do sistema não foram esquecidos, mas a documentação estilo DOxygen foi a que mereceu mais atenção, pois as classes ficam documentadas facilitando o seu entendimento sem nem mesmo ver o código fonte.

Os dois motivos que levaram à adoção do DOxygen foram a integração do KDevelop e a sua utilização no projeto KDE. O KDevelop pode usar outros sistemas como o kdoc ou javadoc para documentar a API do projeto, mas como padrão ele sugere o DOxygen. O fato do KDevelop usar o DOxygen como padrão provavelmente é decorrência dele ter sido adotado pelo projeto KDE para documentar a sua própria API.

Para elaborar a documentação do sistema, manual do usuário e até mesmo este trabalho, poderia ter sido utilizado qualquer processador de texto como o OpenOffice ou o Microsoft Word. Porém, seguindo as especificações da TLDP - The Linux Documentation Project, foi utilizado o DocBook, que gera a documentação em HTML, PDF, LaTeX, PostScript entre outros formatos a partir de um mesmo fonte XML (Extensible Markup Language) ou SGML (Standard Generalized Markup Language).