Documentação XML

Publicado: 30/10/2004 em IntoSpaces

Lendo o belíssimo livro Desenvolvendo com C#, econtrei um apêndice muito interessante e útil que destaca a documentação XML proporcionada pelo C#.
Resolvi postar aqui, pois acredito ser do interesse de todos essa feature da linguagem que nos ajuda tanto na documentação e integração com o Visual Studio.

Para conferir o livro veja o post http://br.thespoke.net/BlogReader/SingleEntry.aspx?ID=4561
Ou então vá direto ao site da Livraria Cultura
http://www.livrariacultura.com.br/scripts/cultura/resenha/resenha.asp?nitem=5013282&sid=01617418361021336577009060&k5=39639B37&uid==

Todos os exemplos do livro estão disponibilizados no endereço http://www.shindesign.net/Livros/DesenvolvendoComCsharp/ExemplosLivroCsharp.zip

Eu considero essa literatura uma leitura obrigatória sobre a linguagem C#, aproveitem e espero que seja tão útil para vocês como foi e é pra mim.

Obrigado Fabio pelo texto e pelos arquivos e pela autorização!

Documentação XML
Junto ao código que será compilado, o C# permite que você escreva a documentaão do programa de forma “in-line” ou a referencie através de elementos XML.

Quando o argumento de compilador /d ou /doc for utilizado, o compilador C# processará os comentários e criará um arquivo XML com a documentaão.

Os 18 elementos XML que poderão ser usados junto aos tipos e membros são padronizados e estão descritos na tabela 1.

Tabela 1: Elementos XML para  documentaão

Elemento XML

Descrião

<c>

Indica que o texto dentro de uma descrião deverá ser marcado como código

<code>

Este elemento é a versão para múltiplas linhas do elemento <c>

<example>

Indica um exemplo de como um membro ou um tipo deverá ser utilizado

<exception>

Representa que exceões poderão ser disparadas

<include>

Referencia comentários em outro arquivo. Ele é uma alternativa para não colocar a documentaão diretamente no arquivo

<list>

Este elemento é usado na definião de uma lista ou tabela. O bloco <listheader> define a linha de cabeçalho, enquanto o bloco <item> especifica um item na lista ou na tabela. Uma lista ou tabela podem ter vários itens. As listas numeradas e bullets são suportadas

<para>

Este elemento é usado dentro de outros elementos. Ele indica um novo parágrafo

<param>

Aplicado em membros para descrever seus parâmetros

<paramref>

Este elemento é usado para indicar que uma palavra é parâmetro

<permission>

Descreve a permissão de acesso de um membro

<remarks>

Aplicado em membros e tipos, indicando na documentaão um overview ou uma informaão sobre o item documentado.

<returns>

Aplicado para descrever o retorno de um membro

<see>

Especifica um link dentro de um texto

<seealso>

Indica que o texto deverá aparecer na sessão See Also

<summary>

Usado para descrever detalhadamente um membro ou um tipo

<value>

Usado para descrever uma propriedade

O suporte de documentaão XML aliado a XSL e ao Help Workshop possibilita a criaão de documentaão e help compilado (.chm) semelhante à documentaão que acompanha o .NET Framework.

O exemplo abaixo aplica a documentaão XML juntamente com o código-fonte do programa:

//csc /t:library MessageQueue.cs /doc:MessageQueue.xml 
using System; 

/// <summary>
/// Representa uma fila de mensagens
/// </summary>

public class MessageQueue
{
  string[] queue;
  int idx; 

  /// <summary>
  /// Cria uma nova instância da classe MessageQueue
  /// </summary>
  /// <param name="size">Capacidade de mensagens suportadas</param>
  /// <exception cref="System.ArgumentOutOfRangeException">
  /// Quando o argumento size for menor do que 0
  /// </exception>
  public MessageQueue(int size)
  {
    if(size < 0)
      throw new ArgumentOutOfRangeException("size deve ser maior que 0");   

    queue new string[size];
    idx = 0;
  } 

  /// <summary>
  /// Insere uma mensagem na fila
  /// </summary>
  /// <remarks>
  /// A mensagem é uma string.
  /// <para>Se a fila estiver cheia a mensagem será ignorada</para> 
  /// </remarks>
  /// <param name="msg">Representa uma mensagem</param>
  /// <example>
  /// <code>
  /// MessageQueue mq = new MessageQueue(10);
  ///
  /// for(int a = 0; a != 10; a++)
  ///   mq.Enqueue("Msg" + (a + 1).ToString());
  /// </code>
  /// </example>
  /// <seealso cref="Dequeue"/>
  public void Enqueue(string msg)
  {
    if(!IsFull)
      queue[idx++] = msg;
  } 

  /// <summary>
  /// Retira uma mensagem na fila
  /// </summary>
  /// <remarks>
  /// A mensagem é uma string.
  /// <para>Se a fila estiver vazia uma exceão será disparada</para> 
  /// </remarks>
  /// <returns>Uma mensagem</returns>
  /// <exception cref="System.ApplicationException">
  /// Quando a fila estiver vazia
  /// </exception>
  /// <example>
  /// <code>
  /// MessageQueue mq new MessageQueue(10);
  ///
  /// for(int a = 0; a != 10; a++) 
  ///   mq.Enqueue("Msg" + (a + 1).ToString());
  ///
  /// if(mq.IsFull)
  ///   for(int a = 0; a != 10; a++)
  ///     System.Console.WriteLine(mq.Dequeue());
  /// </code>  
  /// </example>
  /// <seealso cref="Enqueue"/>
  public string Dequeue()
  {
    if(idx > 0)
    {
      string msgtmp = queue[queue.Length – idx];
      idx–;
      return msgtmp;
    }
    throw new ApplicationException("Queue is empty");
  } 

  /// <value>Verifica se a fila está cheia</value>
  /// <example> O exemplo encontra-se no método <see cref="Dequeue"/>.</example>
  public bool IsFull
  {get{ return idx = queue.Length; } 
}

Deixe uma resposta

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s