Documentação no Visual Basic .NET 2005 utilizando comentários XML
Uma das muitas funcionalidades do Visual Studio.NET está na possibilidade de transformar comentários dos nossos códigos em documentação. Diferentemente da versão 2003, o Visual Basic.Net agora suporta nativamente (sem a necessidade de instalação de programas de terceiros, como o VBCommenter) a criação de comentários em XML para posterior documentação do nosso software. O foco desse artigo é apresentar como realizar esse tipo de documentação no VB2005 e mostrar como gerar o arquivo de documentação a partir da ferramenta: NDOC.
A ferramenta NDoc gera a documentação para o seu código partir dos comentários XML em um formato pré-definido, que pode ser no formato da documentação MSDN ou em no padrão do Html Help Files (.chm) do Microsoft Windows. Para obter o NDoc, faça o download em: http://ndoc.sourceforge.net/.
Para comentar um código em Visual Basic.Net usamos aspas simples ( ' ) Comentários que começam com três aspas simples ( ''' ror irá gerar entererceirosç(( ), constituem a documentação XML do seu código, dessa forma documentando o código com este tipo de comentário, o compilador irá gerar automaticamente toda a documentação para o sistema desenvolvido.
Figura 1 – Comentário utilizando XML.
Para apresentar a documentação XML , vamos definir a estrutura de um pequeno projeto de demonstração, que será composto de:
1. Um projeto do Tipo ClassLibray para definição das classes.
2. Um projeto do Tipo Windows Application para criação da interface.
Inicialmente vamos criar um projeto Windows Application que chamei de:
InterfaceDocumentacaoXML.
Figura 2 – Adicionando um novo projeto.
Logo em seguida, crie um novo projeto do tipo Class Library nomeando para ClassesDocumentacaoXML.
Com os dois projetos criados é o momento de escrever o código e documenta-lo usando as TAGs XML disponíveis para documentação. Adicione uma nova classe ao projeto ClassesDocumentacaoXML (Add -> Class) nomeando para clsFuncionario.
Coloque o cursor do teclado sobre a sintaxe da declaração da classe clsFuncionário e pressione a tecla aspas simples por três vezes para que o Visual Studio.Net possa escrever automaticamente o bloco de comentários XML. Veja na figura abaixo como deve ficar o resultado.
Figura 3 – Bloco de Documentação XML para a Classe.
A tag : <summary></summary> define a descrição/objetivo/sumário do trecho de código comentado.
Faça o mesmo procedimento para os atributos, métodos, propriedades e construtores da classe. Na figura abaixo temos o bloco de documentação XML para o método CalculaSalario.
Figura 4 – Bloco de Documentação XML para o método CalculaSalario.
A tag : <param name=""> define a descrição dos parâmetros dos métodos declarados caso existam, e a tag <returns> </returns> define o retorno da função. As tags XML são adicionadas automaticamente pelo Visual Studio.Net de forma que será adicionado as tags realmente necessárias para documentação.
Com a classe finalizada e comentada usando XML, vamos ver a funcionalidade dessa documentação e o porquê da sua utilização. Voltaremos ao projeto Windows Application, e no Form1 vamos desenhar 3 textbox, 3 labels e 1 button de forma que o formulário fique semelhante a figura abaixo.
Figura 5 – Formulário.
Vamos agora ao código do formulário e no evento click vamos declarar um objeto do tipo clsFuncionario. (Obs. Será necessário adicionar uma reference no projeto Windows Application para acessar a dll gerada no projeto Class Library e importa-lo no formulário Form1). Nesse momento podemos observar que o Intelisense do Visual Studio.Net entrou em atividade e apresenta a documentação XML comentada na classe Funcionário.
Figura 6a – Intelisense em Ação.
Na outra imagem abaixo, vemos novamente o Intelisense em ação no momento em que o usuário chama o método InserirFuncionario, apresentando a descrição do método a partir da documentação XML.
Figura 6b – Intelisense em Ação.
Para disponibilizar uma documentação do projeto criado, vamos utilizar o programa NDoc citado no início da matéria. Inicie o aplicativo NDoc e adicione um novo projeto a partir do Menu Project. Clique no botão Add para adiconar um assembly ao projeto, que no nosso caso será a dll gerada pelo projeto Class Libray.
Figura 7 – Adicionando um Novo Projeto no NDoc.
Agora defina o tipo de documentação a ser criada, para este projeto escolhi MSDN 2003. Para finalizar é hora de dar um Build na solução, para isso clique no menu Documentation->Build ou no ícone referente a essa funcionalidade. ( Obs: Não esqueça de alterar a propriedade HtmlHelpName para especificar um nome para o arquivo de ajuda HTML que será gerado). Altere também a propriedade OutPutDirectory para definir o diretório onde você deseja armazenar a documentação.
Selecione os arquivos e no menu Documentation 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 ocorrer corretamente o arquivo de documentação será gerado de acordo com o tipo definido.
Chegamos ao final do artigo e podemos ver a importância de um código fonte bem documentado em qualquer projeto, trazendo aos desenvolvedores facilidade e produtividade na criação do seu código.
Até o próximo.
Regilan Meira
