Documentando código .NET

Veja nesse artigo uma forma de documentar código com o .NET.

por Ramon Durães

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 .csharpcode, .csharpcode pre { font-size: small; color: black; font-family: Consolas, "Courier New", Courier, Monospace; background-color: #ffffff; /*white-space: pre;*/ } .csharpcode pre { margin: 0em; } .csharpcode .rem { color: #008000; } .csharpcode .kwrd { color: #0000ff; } .csharpcode .str { color: #006080; } .csharpcode .op { color: #0000c0; } .csharpcode .preproc { color: #cc6633; } .csharpcode .asp { background-color: #ffff00; } .csharpcode .html { color: #800000; } .csharpcode .attr { color: #ff0000; } .csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em; } .csharpcode .lnum { color: #606060; }

   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

Projeto.XML

.csharpcode, .csharpcode pre { font-size: small; color: black; font-family: Consolas, "Courier New", Courier, Monospace; background-color: #ffffff; /*white-space: pre;*/ } .csharpcode pre { margin: 0em; } .csharpcode .rem { color: #008000; } .csharpcode .kwrd { color: #0000ff; } .csharpcode .str { color: #006080; } .csharpcode .op { color: #0000c0; } .csharpcode .preproc { color: #cc6633; } .csharpcode .asp { background-color: #ffff00; } .csharpcode .html { color: #800000; } .csharpcode .attr { color: #ff0000; } .csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em; } .csharpcode .lnum { color: #606060; }

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

  16:    <summary>Classe para demonstração do 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.

Verificou como foi fácil gerar a documentação do projeto? A difícil tarefa agora é fazer com que o seu 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.