.NET - Criando Documentação XML para suas aplicações

NO ciclo do desenvolvimento de software a documentação tem um papel muito importante, senão fundamental, afinal de que adiante um software se você não tem como obter informações em detalhes sobre ele ?

Pois é  na criação da documentação, que deve ser um processo contínuo ao logo de todo processo de desenvolvimento, e, não uma tarefa deixada para quanto o software estiver pronto, que a grande parte dos desenvolvedores torce o nariz, julgando um trabalho não importante e secundário.

O problema é que documentar dá trabalho mas compensa.

Existem muitas ferramentas que ajudam no processo de geração da documentação mas neste artigo eu vou mostrar como criar a documentação no formato XML para suas aplicações na plataforma .NET usando os recursos nativos da plataforma. Depois, se você achar que precisa de algo mais sofisticado poderá incrementar o seu trabalho com ferramentas de terceiros.

Obs: Uma ferramenta que gera documentação no estilo MSDN é a SandCastle que você pode obter neste link:http://sandcastle.codeplex.com/

Comentar e documentar o seu código é uma das tarefas básicas da documentação de um sistema e é esse aspecto que esse artigo vai explorar.

Este artigo mostra que com a ajuda do intellSense e do compilador da plataforma .NET você pode gerar a documentação a nível de código no formato XML.

Criar a documentação do seu código na plataforma .NET requer que você apenas use os marcadores de comentários.

Mas o que são esses marcadores de comentários ?

Os marcadores ou indicadores de comentários são marcas que você coloca no seu código que indicam ao compilador que ali você deseja que seja considerado um comentário.

Na linguagem VB .NET o marcador são três aspas simples ''' que você digita antes da assinatura de um método ou rotina. Ao fazer isso será criado 4 linhas conforme mostrada na figura abaixo sendo a primeira : ''' <summary> e última '''<remarks> </remarks>;

Para a linguagem C# os marcadores de documentação são três barras /// que gera o código de comentário exibido na figura a seguir:

Observe que em cada linguagem temos um conjunto de tags XML que são geradas, e, além delas existem outras tags XML que você pode usar para definir os seus comentários.  Com a ajuda do IntelliSense você pode visualizar a lista de tags na linguagem que esta usando conforme  mostra a figura abaixo:

Como todas as tags XML você coloca texto no interior das tags abrindo-as <> e depois fechando-as </>. Como exemplo  temos o trecho de código a seguir que exibe alguns comentários na linguagem Visual Basic :

A tabela abaixo lista algumas das tags XML recomendadas tanto para a linguagem C# como para VB .NET.

Tag XML Descrição
<c>
Esta tag é utilizada para designar o código, por isso podem ser usadas para identificar o código de exemplo associado a uma entidade particular dentro do código fonte. Note-se que a tag só pode ser usada para representar uma única linha de código ou para indicar que parte do texto em uma linha deve ser marcado como código. Exemplo:  <c > Dim oExemplo  As Object </ c >
<code> Esta tag é utilizada para designar mais de uma linha de código, por isso podem ser usadas para identificar as áreas mais longas de código de exemplo
<example>
Esta tag pode ser usada para descrever um exemplo do uso de um determinado método ou classe. É possível incluir exemplos de código dentro da tag por exemplo, fazendo uso de qualquer das marcas c ou código.
<exception> Esta tag permite que um método de exceção seja documentado. O atributo cref permite que o espaço do manipulador de exceção possa ser incluído. Exemplo: <exception cref="System.Exception">Lança uma exceção se o cliente não for localizado.</exception>
<include> Permite que a documentação seja importada a partir de um arquivo XML externo ao invés de ser armazenado dentro do próprio código. Pode ser útil se a documentação é escrita por outras pessoas que não os desenvolvedores.
<list> Permite que listas numeradas ou tabelas a sejam adicionados aos comentários XML.
<para> Indica que o texto dentro das tags deve ser formatado como um parágrafo. Como tal, pode ser usado para formatar o texto dentro de outras tags tais como summary ou returns. Exemplo: <para> Este é um parágrafo </ para>
<param> É usada para documentar os argumentos de um método. O atributo name da tag especifica o nome do argumento ao qual a tag se refere. A tag também usada pelo IntelliSense para exibir uma descrição dos argumentos dos métodos. Também pode ser usada pelo Object Browser. Exemplo: <param name="FileName"> O Nome do arquivo a ser carregado.</param>
<paramref> Essa tag pode ser usada para se referir ao argumento de um método em outro lugar dentro dos comentários XML do método. O atributo name da tag especifica o nome do argumento a que a marca se refere. Note que a tag param realmente é usada para descrever o parâmetro. Exemplo: Use o argumento <paramref name="FileName"/> para especificar o nome do arquivo a ser carregado.
<permission> Esta tag pode ser usada para descrever as permissões especiais que um objeto especifico precisa. O objeto ao qual a permissão se refere esta incluído como um atributo cref.
<remarks> Esta tag pode ser usada para fornecer informações adicionais sobre um  sobre um método ou classe, completando as indicações dadas na tag de resumo (summary). Como a tag summary, essa tag também é usada pelo Intellisense e pelo Object Browser.
<returns>
Descreve o valor de retorno de um método. Exemplo: <returns> True se o usuário tem permissão para acessar o recurso, caso contrário, False </ returns>.
<see> Esta tag é usada praa referenciar outras entidades (como classes) no projeto. A tag see se destina ao uso no interior de outras tags como a tag summary. Exemplo: <see cref="System.Configuration"/>
<seealso> Esta se parece com a tag see e possui um sintaxe idêntica, exceto que o texto se destina a ser usado para criar uma seção seealso separada para documentação da entidade.
<summary> Esta tag descreve um método ou uma classe, por isso é a tag mais importante. Para além de ser utilizado na documentação do projeto, a tag também é usada pelo sistema IntelliSense para mostrar uma descrição do método ou classe que está sendo referenciado. Também é usado pelo Object Browser.
<typeparam>
Typeparam é utilizada de forma idêntica aos parâmetros, exceto que ele é utilizado para documentar um tipo associado a uma classe ou função genérica.
<value> A tag value é usada somente quando documentamos uma propriedade, e é usada para descrever o valor atribuído a ela. O comentário náo é exigido para propriedades que são marcadas como somente leitura. Exemplo: <value>Define o valor do salário </value>

Quando você compilar o seu projeto usando o parâmetro /doc o compilador irá procurar pelas tags XML no código fonte e irá criar um arquivo XML com a documentação. Para criar a documentação final com o arquivo XML gerado você pode usar uma ferramenta como o Sandcastle, ou criar a sua própria ferramenta.

A seguir temos uma tabela com dicas sobre quais tags XML você pode usar dependendo do tipo ou do membro existente no código do seu projeto:

Tipo/Membro Tags XML (sugestão)
Classes Summary, Remarks e Example (if necessary)
Métodos Summary, Remarks, Param, Returns e Exception
Propriedades Summary, Value, Remarks e Exception
Na tag Summary indicar se a propriedade é read/write, read-only ou write-only

Ao incluir esta informação na tag Summary , o desenvolvedor será capaz de vê-la no
IntelliSense quando ele for consumir a library.
 
Campos Summary
Constantes Summary e Value
A tag específica Value indica o valor da constate e permite que o mesmo seja visto no IntelliSense.
Delegates Summary, Remarks, Param e Returns

Parte Prática - Criando uma documentação XML bem simples

Vamos por em prática a teoria acima gerando um arquivo de documentação para um programa VB .NET bem simples.

Obs:  A documentação sobre o assunto para VB .NET deixa a desejar deixando várias lacunas de informação que faz com que o desenvolvedor tenha que se virar para descobrir como a coisa funciona.

Eu vou usar o Visual Basic 2010 Express Edition e criar uma aplicação do tipo Windows Forms Application chamada CalculadoraNatural;

Veja a seguir o leiaute do formulário da aplicação:

A seguir eu vou criar uma classe com no projeto chamada CalculadoraNatural que irá conter os 4 métodos : Somar, Subtrair, Multiplicar e Dividir, que irão efetuar cálculos com números naturais.

Para incluir uma classe no projeto selecione o menu Project -> Add Class e informe o nome Calculos.vb :

A seguir inclua o código a seguir nesta classe incluindo as tags XML para documentação para o VB .NET:

Obs: Estou excluindo o número zero do conjunto dos números naturais.

Public Class Calculos
    ''' <summary>
    ''' Funçao Somar - Soma dois números inteiros: n1 + n2
    ''' </summary>
    ''' <param name="n1">n1</param>
    ''' <param name="n2">n2</param>
    ''' <returns>retorna a soma dos dois números naturais</returns>
    ''' <remarks>n1 e n2 tem que ser maior que zero</remarks>
    Public Function Somar(ByVal n1 As Integer, ByVal n2 As Integer) As Integer
        If n1 = 0 Or n2 = 0 Then
            Throw New Exception("Os números naturais tem que ser maior que zero.")
        Else
            Return n1 + n2
        End If
    End Function

    ''' <summary>
    ''' Função Subtrair - Subtrai dois números inteiros : n1 - n2
    ''' </summary>
    ''' <param name="n1">n1</param>
    ''' <param name="n2">n2</param>
    ''' <returns>Retorna a diferença entre os dois números naturais</returns>
    ''' <remarks>n1 tem que ser maior que n2</remarks>
    Public Function Subtrair(ByVal n1 As Integer, ByVal n2 As Integer) As Integer
        If n2 > n1 Then
            Throw New Exception("O primeiro número natural tem que ser maior que o primeiro")
        Else
            Return n1 - n2
        End If
    End Function
 
    ''' <summary>
    ''' Função Multiplicar - Calcula o valor da multiplicação entre dois números naturais
    ''' </summary>
    ''' <param name="n1">n1</param>
    ''' <param name="n2">n2</param>
    ''' <returns>Um número natural que representa o valor de n1xn2</returns>
    ''' <remarks>Os números naturais tem que ser maior que zero</remarks>
    Public Function Multiplicar(ByVal n1 As Integer, ByVal n2 As Integer) As Integer
        If n1 = 0 Or n2 = 0 Then
            Throw New Exception("Os números naturais tem que ser maior que zero.")
        Else
            Return n1 * n2
        End If
    End Function
 
    ''' <summary>
    ''' Função Dividir - Calcula o valor da divisão entre dois número naturais : n1/n2
    ''' </summary>
    ''' <param name="n1">n1</param>
    ''' <param name="n2">n2</param>
    ''' <returns>Retorna a parte inteira do resultado da divisão entre os dois números</returns>
    ''' <remarks>O primeiro número(dividendo) tem que ser maior que o segundo (divisor) , e o divisor não pode ser igual a zero</remarks>
    Public Function Dividir(ByVal n1 As Integer, ByVal n2 As Integer) As Integer
        If n2 > n1 Then
            Throw New Exception("O primeiro número natural tem que ser maior que o primeiro")
        ElseIf n1 = 0 Then
            Throw New Exception("O divisor não pode ser igual a zero")
        Else
            Return CInt(n1 / n2)
        End If
    End Function
End Class

 

Agora vejamos como gerar o arquivo XML referente a documentação no projeto Visual Basic.

Clique sobre o nome do projeto e no menu suspenso selecione Properties;

A seguir na guia Debug informe em : Command line arguments => /doc:CalculadoraNatural.xml

Dessa forma quando compilarmos a aplicação será gerado o arquivo CalculadoraNatural.xml na pasta /bin/Release do projeto;

Na janela Solution Explorer clique o ícone Show all files para exibir os arquivos do projeto:

Se espiarmos na pasta do projeto via Windows Explorer veremos o arquivo conforme a figura abaixo:

Abrindo o arquivo CalculadoraNatural.xml iremos obter:

<?xml version="1.0"?>

<doc>

<assembly>

<name>

CalculadoraNatural

</name>

</assembly>

<members>

<member name="M:CalculadoraNatural.Calculos.Somar(System.Int32,System.Int32)">

<summary>

Funçao Somar - Soma dois números inteiros: n1 + n2

</summary>

<param name="n1">n1</param>

<param name="n2">n2</param>

<returns>retorna a soma dos dois números naturais</returns>

<remarks>n1 e n2 tem que ser maior que zero</remarks>

</member><member name="M:CalculadoraNatural.Calculos.Subtrair(System.Int32,System.Int32)">

<summary>

Função Subtrair - Subtrai dois números inteiros : n1 - n2

</summary>

<param name="n1">n1</param>

<param name="n2">n2</param>

<returns>Retorna a diferença entre os dois números naturais</returns>

<remarks>n1 tem que ser maior que n2</remarks>

</member><member name="M:CalculadoraNatural.Calculos.Multiplicar(System.Int32,System.Int32)">

<summary>

Função Multiplicação - Cálcula o valor da multplicação entre dois números naturais

</summary>

<param name="n1">n1</param>

<param name="n2">n2</param>

<returns>Um número natural que representa o valor de n1xn2</returns>

<remarks>Os números naturais tem que ser maior que zero</remarks>

</member><member name="M:CalculadoraNatural.Calculos.Dividir(System.Int32,System.Int32)">

<summary>

Função Dividir - Cálcula o valor da divisão entre dois número naturais : n1/n2

</summary>

<param name="n1">n1</param>

<param name="n2">n2</param>

<returns>Retorna a parte inteira do resultado da divisão entre os dois números</returns>

<remarks>O primeiro número tem que ser maior que o segundo e o divisor não pode ser igual a zero</remarks>

</member><member name="P:CalculadoraNatural.My.Resources.Resources.ResourceManager">

<summary>

Returns the cached ResourceManager instance used by this class.

</summary>

</member><member name="P:CalculadoraNatural.My.Resources.Resources.Culture">

<summary>

Overrides the current thread's CurrentUICulture property for all

resource lookups using this strongly typed resource class.

</summary>

</member><member name="T:CalculadoraNatural.My.Resources.Resources">

<summary>

A strongly-typed resource class, for looking up localized strings, etc.

</summary>

</member>

</members>

</doc>

 

Com o documento XML gerado temos duas opções para gerar a documentação:

Na primeira opção você deve colocar o arquivo XLST no mesmo local onde o arquivo XML foi gerado e usar um editor que interprete XLST como o Internet Explorer.

Eu estou colocando o arquivo documentacaoXML.xls  que você pode usar para testar a geração da documentação porém será preciso realizar ajustes no código.

Pegue o projeto completo aqui: CalculadoraNatural.zip

Eu sei é apenas VB .NET mas eu gosto

Referências:

José Carlos Macoratti