Criação de Comentários e Documentação em VB.NET

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...

por Israel Aéce

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.