.

NET - Criando Documentao XML para suas aplicaes

NO ciclo do desenvolvimento de software a documentao tem um papel muito importante, seno fundamental, afinal de que adiante um software se voc no tem como obter informaes em detalhes sobre ele ? Pois na criao da documentao, que deve ser um processo contnuo ao logo de todo processo de desenvolvimento, e, no uma tarefa deixada para quanto o software estiver pronto, que a grande parte dos desenvolvedores torce o nariz, julgando um trabalho no importante e secundrio. O problema que documentar d trabalho mas compensa. Existem muitas ferramentas que ajudam no processo de gerao da documentao mas neste artigo eu vou mostrar como criar a documentao no formato XML para suas aplicaes 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 documentao no estilo MSDN a SandCastle que voc pode obter neste link:http://sandcastle.codeplex.com/ Comentar e documentar o seu cdigo uma das tarefas bsicas da documentao 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 documentao a nvel de cdigo no formato XML. Criar a documentao do seu cdigo na plataforma .NET requer que voc apenas use os marcadores de comentrios. Mas o que so esses marcadores de comentrios ? Os marcadores ou indicadores de comentrios so marcas que voc coloca no seu cdigo que indicam ao compilador que ali voc deseja que seja considerado um comentrio. Na linguagem VB .NET o marcador so trs aspas simples ''' que voc digita antes da assinatura de um mtodo 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 documentao so trs barras /// que gera o cdigo de comentrio exibido na figura a seguir:

Observe que em cada linguagem temos um conjunto de tags XML que so geradas, e, alm delas existem outras tags XML que voc pode usar para definir os seus comentrios. 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 cdigo a seguir que exibe alguns comentrios na linguagem Visual Basic :

A tabela abaixo lista algumas das tags XML recomendadas tanto para a linguagem C# como para VB .NET. Tag XML <c>
Descrio Esta tag utilizada para designar o cdigo, por isso podem ser usadas para identificar o cdigo de exemplo associado a uma entidade particular dentro do cdigo fonte. Note-se que a tag s pode ser usada para representar uma nica linha de cdigo ou para indicar que parte do texto em uma linha deve ser marcado como cdigo. Exemplo: <c > Dim oExemplo As Object </ c > Esta tag utilizada para designar mais de uma linha de cdigo, por isso podem ser usadas para identificar as reas mais longas de cdigo de exemplo Esta tag pode ser usada para descrever um exemplo do uso de um determinado mtodo ou classe. possvel incluir exemplos de cdigo dentro da tag por exemplo, fazendo uso de qualquer das marcas c ou cdigo. Esta tag permite que um mtodo de exceo seja documentado. O atributo cref permite que o espao do manipulador de exceo possa ser includo. Exemplo: <exception cref="System.Exception">Lana uma exceo se o cliente no for localizado.</exception> Permite que a documentao seja importada a partir de um arquivo XML externo ao invs de ser armazenado dentro do prprio cdigo. Pode ser til se a documentao escrita por outras pessoas que no os desenvolvedores. Permite que listas numeradas ou tabelas a sejam adicionados aos comentrios XML. Indica que o texto dentro das tags deve ser formatado como um pargrafo. Como tal, pode ser usado para formatar o texto dentro de outras tags tais como summary ou returns. Exemplo: <para> Este um pargrafo </ para> usada para documentar os argumentos de um mtodo. O atributo name da tag especifica o nome do argumento ao qual a tag se refere. A tag tambm usada pelo IntelliSense para exibir uma descrio dos argumentos dos mtodos. Tambm pode ser usada pelo Object Browser. Exemplo: <param name="FileName"> O Nome do arquivo a ser carregado.</param> Essa tag pode ser usada para se referir ao argumento de um mtodo em outro lugar dentro dos comentrios XML do mtodo. 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 parmetro. Exemplo: Use o argumento <paramref name="FileName"/> para especificar o nome do arquivo a ser carregado. Esta tag pode ser usada para descrever as permisses especiais que um objeto especifico precisa. O objeto ao qual a permisso se refere esta includo como um atributo cref. Esta tag pode ser usada para fornecer informaes adicionais sobre um sobre um mtodo ou classe, completando as indicaes dadas na tag de resumo (summary). Como a tag summary, essa tag tambm usada pelo Intellisense e pelo Object Browser. Descreve o valor de retorno de um mtodo. Exemplo: <returns> True se o usurio tem permisso para acessar o recurso, caso contrrio, False </ returns>. 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"/> Esta se parece com a tag see e possui um sintaxe idntica, exceto que o texto se destina a ser usado para criar uma seo seealso separada para documentao da entidade. Esta tag descreve um mtodo ou uma classe, por isso a tag mais importante. Para alm de ser utilizado na documentao do projeto, a tag tambm usada pelo sistema IntelliSense para mostrar uma descrio do mtodo ou classe que est sendo referenciado. Tambm usado pelo Object Browser. Typeparam utilizada de forma idntica aos parmetros, exceto que ele utilizado para documentar um tipo associado a uma classe ou funo genrica. A tag value usada somente quando documentamos uma propriedade, e usada para descrever o valor atribudo a ela. O comentrio no exigido para propriedades que so marcadas como somente leitura. Exemplo: <value>Define o valor do salrio </value>

<code> <example>

<exception>

<include> <list> <para>

<param>

<paramref>

<permission> <remarks> <returns> <see> <seealso> <summary> <typeparam> <value>

Quando voc compilar o seu projeto usando o parmetro /doc o compilador ir procurar pelas tags XML no cdigo fonte e ir criar um arquivo XML com a documentao. Para criar a documentao final com o arquivo XML gerado voc pode usar uma ferramenta como o Sandcastle, ou criar a sua prpria ferramenta.

A seguir temos uma tabela com dicas sobre quais tags XML voc pode usar dependendo do tipo ou do membro existente no cdigo do seu projeto: Tipo/Membro Classes Mtodos Tags XML (sugesto) Summary, Remarks e Example (if necessary) Summary, Remarks, Param, Returns e Exception Summary, Value, Remarks e Exception Na tag Summary indicar se a propriedade read/write, read-only ou write-only Propriedades Ao incluir esta informao na tag Summary , o desenvolvedor ser capaz de v-la no IntelliSense quando ele for consumir a library. Campos Constantes Delegates A tag especfica Value indica o valor da constate e permite que o mesmo seja visto no IntelliSense. Summary, Remarks, Param e Returns Summary Summary e Value

Parte Prtica - Criando uma documentao XML bem simples

Vamos por em prtica a teoria acima gerando um arquivo de documentao para um programa VB .NET bem simples. Obs: A documentao sobre o assunto para VB .NET deixa a desejar deixando vrias lacunas de informao 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 aplicao do tipo Windows Forms Application chamada CalculadoraNatural; Veja a seguir o leiaute do formulrio da aplicao:

A seguir eu vou criar uma classe com no projeto chamada CalculadoraNatural que ir conter os 4 mtodos : Somar, Subtrair, Multiplicar e Dividir, que iro efetuar clculos com nmeros naturais. Para incluir uma classe no projeto selecione o menu Project -> Add Class e informe o nome Calculos.vb :

A seguir inclua o cdigo a seguir nesta classe incluindo as tags XML para documentao para o VB .NET: Obs: Estou excluindo o nmero zero do conjunto dos nmeros naturais. Public Class Calculos ''' <summary> ''' Funao Somar - Soma dois nmeros inteiros: n1 + n2 ''' </summary> ''' <param name="n1">n1</param> ''' <param name="n2">n2</param> ''' <returns>retorna a soma dos dois nmeros 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 nmeros naturais tem que ser maior que zero.") Else Return n1 + n2 End If End Function ''' <summary> ''' Funo Subtrair - Subtrai dois nmeros inteiros : n1 - n2 ''' </summary> ''' <param name="n1">n1</param> ''' <param name="n2">n2</param> ''' <returns>Retorna a diferena entre os dois nmeros 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 nmero natural tem que ser maior que o primeiro") Else Return n1 - n2 End If End Function ''' <summary> ''' Funo Multiplicar - Calcula o valor da multiplicao entre dois nmeros naturais ''' </summary> ''' <param name="n1">n1</param> ''' <param name="n2">n2</param> ''' <returns>Um nmero natural que representa o valor de n1xn2</returns> ''' <remarks>Os nmeros 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 nmeros naturais tem que ser maior que zero.") Else Return n1 * n2 End If End Function

''' <summary> ''' Funo Dividir - Calcula o valor da diviso entre dois nmero naturais : n1/n2 ''' </summary> ''' <param name="n1">n1</param> ''' <param name="n2">n2</param> ''' <returns>Retorna a parte inteira do resultado da diviso entre os dois nmeros</returns> ''' <remarks>O primeiro nmero(dividendo) tem que ser maior que o segundo (divisor) , e o divisor no 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 nmero natural tem que ser maior que o primeiro") ElseIf n1 = 0 Then Throw New Exception("O divisor no 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 documentao 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 aplicao 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 Window s 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> Funao Somar - Soma dois nmeros inteiros: n1 + n2 </summary> <param name="n1">n1</param> <param name="n2">n2</param> <returns>retorna a soma dos dois nmeros 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> Funo Subtrair - Subtrai dois nmeros inteiros : n1 - n2 </summary> <param name="n1">n1</param> <param name="n2">n2</param> <returns>Retorna a diferena entre os dois nmeros naturais</returns> <remarks>n1 tem que ser maior que n2</remarks> </member><member name="M:CalculadoraNatural.Calculos.Multiplicar(System.Int32,System.Int32)"> <summary> Funo Multiplicao - Clcula o valor da multplicao entre dois nmeros naturais </summary> <param name="n1">n1</param> <param name="n2">n2</param> <returns>Um nmero natural que representa o valor de n1xn2</returns> <remarks>Os nmeros naturais tem que ser maior que zero</remarks> </member><member name="M:CalculadoraNatural.Calculos.Dividir(System.Int32,System.Int32)"> <summary> Funo Dividir - Clcula o valor da diviso entre dois nmero naturais : n1/n2 </summary> <param name="n1">n1</param> <param name="n2">n2</param> <returns>Retorna a parte inteira do resultado da diviso entre os dois nmeros</returns> <remarks>O primeiro nmero tem que ser maior que o segundo e o divisor no 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 opes para gerar a documentao: Escrever o seu prprio arquivo XLST para transformar o documento XML em um formato legvel como HTML, PDF, etc.; Usar um componente de terceiros para automaticamente gerar a documentao; Na primeira opo 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 gerao da documentao porm ser preciso realizar ajustes no cdigo. Pegue o projeto completo aqui: CalculadoraNatural.zip

Eu sei apenas VB .NET mas eu gosto Referncias: http://sandcastle.codeplex.com/ http://code.msdn.microsoft.com/VBCommenter

Recommended Tags for Documentation Comments (C# Programming Guide)

Jos Carlos Macoratti