Uma tarefa muito importante no desenvolvimento de um software é sem dúvida a criação de sua documentação. Infelizmente em muitos casos ela é deixada de lado pelos desenvolvedores. Isso dificulta bastante quando o projeto é utilizado por outros desenvolvedores.
No C# intrinsicamente já existem as tags que podemos utilizar e gerar tal documentação. No caso do VB.NET necessitamos de ferramentas à parte para que podemos realizar a mesma tarefa.
Utilizaremos as seguintes ferramentas:
- Visual Studio .NET
- VBCommenter
- NDoc
VBCommenter - Essa ferramenta é responsável para gerar o arquivo XML com os dados que mesclamos junto com o código para gerar a documentação. Esta ferramenta não está incluída no Visual Studio .NET, e deve ser baixada em:
http://www.gotdotnet.com/Community/Workspaces/Workspace.aspx?id=112b5449-f702-46e2-87fa-86bdf39a17dd.
NDoc - Essa ferramenta gera a documentação em um formato pré-definido. Podemos gerar em formato do MSDN ou um próprio HELP, como os padrões do Windows. Para baixá-la:
http://ndoc.sourceforge.net
Para iniciarmos, vamos criar uma nova Aplicação no VS.NET do tipo Class Library. Vá até o Menu File - New - Project, e selecione o Class Library e de o nome de "ComentariosLibrary".
Em um arquivo *.vb vamos criar um classe qualquer para nosso exemplo.
Uma vez instalado o VBCommenter ao digitarmos as três aspas simples ''' ele se encarrega de colocar as tags para que possamos complentar com os dados/descrições que desejarmos.
- Entre as tags "<summary>" colocamos a descrição do método.
- As tags "<param name = "n1">" colocamos a descrição do parâmetro.
- Entre as tags "<returns>" descrevemos o que o método retorna.
- Entre as tags "<remarks>" colocamos algumas informações complementares.
Uma vez colocados esses "Comentários" ao compilarmos o projeto, automaticamente é gerado um arquivo *.xml com as informações que digitamos para descrevemos o metodo.
Na mesma solução, vá até o Menu File - New - Project, e selecione o Windows Application e de o nome de "Comentarios".
Agora precisamos fazer refência nesse projeto ao nosso Class Library ("ComentariosLibrary"). Para isso clique com o botão direito em cima do projeto Windows Application e clique em "Add Reference..." e selecione o arquivo DLL gerando pelo Class Library. Se você nomeou o projeto Class Library como "ComentariosLibrary" a DLL deverá ser ComentariosLibrary.dll.
Depois de adicionado a referência do Class Library no projeto Windows Application, veremos que ao utilizar o método, aparecerá a descrição do método para que o programador possa se orientar e saber o que aquele método faz.
Reparem a tarja amarela que descreve o método que está no Intellisense:
Isso é bastante importante para quando estamos utilizando um componente desenvolvido por outras pessoas. Facilita muito, pois em "design-time" já saberemos o que o método irá fazer e/ou retornar.
Ainda podemos gerar uma documentação mais completa utilizando a ferramenta NDoc. Veremos isso à seguir:
Abra a ferramenta NDoc, clique no botão "Add", selecione a DLL do Class Library e o arquivo *.xml (ComentariosLibrary.xml) gerado pelo VBCommenter.
Abaixo a ferramenta NDoc com o arquivo DLL e XML já selecionados:
Na propriedade OutPutDirectory você seleciona o diretório em que deseja armazenar a documentação.
Selecionados os arquivos clique vá até o menu Documentation e clique em Build.
Depois de gerado a documentação vá até o diretório que você selecionou e procure pelo arquivo index.html.
Se tudo ocorreu corretamente você deverá ter uma tela semelhante à esta:
CONCLUSÃO: Documentação é super importante em qualquer projeto. Com a documentação além de tornar o sistema muito mais "elegante", traz aos programadores/desenvolvedores uma facilidade e agilidade na criação de códigos que fazem uso desses componentes.