Documentando código .NET

Artigo recomendado para Visual Studio 2005;Visual Studio 2008 “Orcas”.

Os diversos trabalhos de consultoria que realizamos nos mais variados clientes, comprovam cada vez mais que desenvolver software é uma tarefa a ser executada com bastante atenção devido a complexidade dos fatores que podem de alguma forma interferir no sucesso do projeto.

Um grande artefato envolvido em todo o projeto, é o próprio código fonte. Quando bem documentado, pode exportar as informações para compor a documentação das classes e ser grande fonte de consulta para outros desenvolvedores do projeto. É muito importante que se estabeleça desde o início do projeto alguns padrões para serem seguidos pelo time de desenvolvimento, sendo o primeiro deles a obrigação de se comentar as classes, métodos e propriedades. Confira na listagem 01 um exemplo de código comentado.

Projeto.cs

1:  namespace ProjetoTEste
   2:  {
   3:      /// <summary>
   4:      /// Classe padrão do projeto
   5:      /// </summary>
   6:      public class ClasseTeste
   7:      {
   8:         /// <summary>
   9:         /// Consulta um cliente
  10:         /// </summary>
  11:         /// <param name="Nome">Nome</param>
  12:         /// <returns>Objeto cliente</returns>
  13:          public Cliente Consultar(string Nome)
  14:          {
  15:              return new Cliente();
  16:          }
  17:      }
  18:   
  19:      /// <summary>
  20:      /// Classe para demonstração do
  21:      /// retorno "Cliente"
  22:      /// </summary>
  23:      ///<remarks>Comentários adicionais</remarks>
  24:      ///<example>Exemplo de uso</example>
  25:      public class Cliente
  26:      { }
  27:      
  28:  }

Listagem 01 – Código comentado.

Com nosso código de exemplo apresentado na listagem 01, primeiramente estamos adicionando o <summary> com informações gerais sobre a classe. Em seguida estamos usando o <param> com informações sobre os parâmetros dos métodos e <returns> para definir o tipo de retorno do método. No outro exemplo na linha 23 com a utilização do <remarks> estamos adicionando um comentário adicional e na linha 24 com o <example> poderemos adicionar um exemplo de utilização.

Após o build, o próprio Visual Studio já oferece suporte para exportar em formato XML todos os comentários que podem ser recuperados posteriormente pela ferramenta Sandcastle e utilizá-los como fonte de informação para geração da documentação.

Para configurar o Visual Studio, vá ao solution explorer, clique no projeto, depois em propriedades do projeto e na opção Build configure a opção listada na figura 01 bastando confirmar o checkbox “XML Docummentation”. No próximo build, ele já vai gerar um arquivo XML na pasta do projeto conforme modelo apresentado na listagem 02.

Figura 01 – Configurando visual studio para gerar XML

1:    <?xml version="1.0" ?> 
   2:  - <doc>
   3:  - <assembly>
   4:    <name>ProjetoTEste</name> 
   5:    </assembly>
   6:  - <members>
   7:  - <member name="T:ProjetoTEste.ClasseTeste">
   8:    <summary>Classe padrão do projeto</summary> 
   9:    </member>
  10:  - <member name="M:ProjetoTEste.ClasseTeste.Consultar(System.String)">
  11:    <summary>Consulta um cliente</summary> 
  12:    <param name="Nome">Nome</param> 
  13:    <returns>Objeto cliente</returns> 
  14:    </member>
  15:  - <member name="T:ProjetoTEste.CÒ^ìOEéØ7nEÜ?y@@¶CìgÀ¨hPá[ËÎ¥>¹Å:P>¼¸B retorno "Cliente"</summary> 
  17:    <remarks>Comentário</remarks> 
  18:    <example>Exemplo de uso</example> 
  19:    </member>
  20:    </members>
  21:    </doc>

Listagem 02 – Comentários exportados em XML.

Conforme você pode observar na listagem 02, todos os comentários já estão dentro do XML. O que falta agora é transformar esse XML em um formato de documento help padrão CHM ou Website.

Utilizaremos a ferramenta Sandcastle que requer ter instalado na máquina o Microsoft HTML Help. O Sandcastle realiza reflection em cima do assembly e une os comentários para montar help, porém, o mesmo não possui uma interface, daí você precisa baixar mais um utilitário que é o Sandcastle Help File Builder conforme figura 02.

Figura 02 – Inteface para o Sandcastle.

No Sandcastle Help File Builder você deve iniciar um novo projeto e adicionar

a referência para os assemblys que você vai gerar a documentação clicando no botão Add conforme figura 03.

Figura 03 – Adicionando assembly

Mantendo a configuração padrão do Visual Studio de acordo com a figura 01, após efetuar o build, ele vai gerar o XML na mesma pasta do projeto. Dai quando você selecionar uma dll, automaticamente o Sandcastle já vai buscar pelo arquivo XML na mesma pasta.

Existe várias propriedades que serão muito úteis para a configuração do output do projeto. Conforme a propriedade configurada, você vai alterar o resultado. Veja um exemplo na propriedade HelpFileFormat mostrada pela figura 04, onde define se o resultado do projeto será um arquivo CHM ou um Website. Você ainda pode fazer diversas outras configurações inclusive definindo o idioma.

Figura 04 – Propriedades.

O próximo passo é efetuar o build da documentação conforme indicação na figura 5.

Figura 05 -Inicio do build.

Ao final, a depender do output escolhido, você vai ter acesso a documentação do seu código de forma a disponibilizar para a sua equipe de desenvolvimento, conforme modelo na figura 06.

Figura 06 -Documentação do projeto.

Time de desenvolvimento, comece desde já a documentar os novos códigos produzidos. Existem ferramentas auxiliares que podem lhe ajudar a cobrar a documentação como o Visual Studio Team System (VSTS) que trataremos em outro artigo.

Sucesso em seu projeto.

Microsoft Sandcastle

Sandcastle Help File Builder

Microsoft HTML Help

http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/