.Net – Documentação Xml

A documentação do .Net é uma das grandes facilidades da tecnologia, assim você vê a diferença no próprio intellisense do Visual Studio e ainda tem no final um arquivo .chm ou um site em html explicando cada método do seu código.

Dica
Ao abrir o Visual Studio e adicionar 3 Barras “/” ( ‘ aspas simples no caso de VB.Net ) em cima de um método, classse ou propriedade, ele mesmo irá criar uma documentação básica para o seu código, basta implementa-lo com os códigos que estudaremos a baixo.

Para comentar o seu código, há algumas tags Básicas em XML, que são:

<summary> … </summary>
Para uma breve descrição de uma classe, método ou propriedade.

<remarks> … </remarks>
Para uma descrição mais detalhada.

<para> … </para>
Permite delinear parágrafos dentro da tag <remarks>

<list type=”…”> … </list>
Permite usar marcadores para formatar uma descrição. Os tipos de marcadores podem ser “bullet”, “number” e “table”.
<example> … </example>
Para disponibilizar um exemplo de como usar um método, propriedade ou outro membro da biblioteca.

<code> … </code>
Para indicar que o texto incluído é código da aplicação.

<c> … </c>
Para indicar que o texto incluído é código da aplicação. É usada para linhas de código que precisam ser separadas da descrição.

<see cref=”member”/>
Indica uma referencia a outro membro ou campo. O compilador verifica se o membro realmente existe.

<exception> … </exception>
Para fazer a descrição de uma exceção.

<permission> … </permission>
Para documentar a acessibilidade.

<param name=”name”> … </param>
Para documentar um parâmetro de um método.

<returns> … </returns>
Para documentar um valor e seu tipo retornado de um método.

<value> … </value>
Para descrever uma propriedade.

Exemplos:

Comentário de uma Classe
/// <summary>
/// Properties of Server Mail
/// </summary>
public class SmtpServerMail{ … }

Propriedades da Classe
/// <summary>
/// Server Smtp Host Properties
/// </summary>
public string Host
{
get { return _host; }
set { _host = value; }
}

Métodos da Classe
/// <summary>
/// Smtp Server Personal Settings (Logged)
/// </summary>
/// <param name=”host”>Host Address</param>
/// <param name=”user”>Username</param>
/// <param name=”pass”>Password</param>
public SmtpServerMail(string host, string user, string pass)
{
Host = host;
IsAnonymous = false;
User = user;
Pass = pass;
}

Utilizando-o

Tudo bem… Você falou, falou, ensinou… Mas aonde isto fará diferença?

É o seguinte, quando você for instanciar a classe, utilizar um método, uma propriedade da classe ou um enumerador, o próprio intellisense do Visual Studio (Aquele que dá as opções de métodos), já te mostrará as informações sobre como utilizar e tudo oque foi comentado!.
Vejamos:

Essa seria uma das partes mais interessantes de se comentar um código…

Porém, ainda assim não satisfeitos, Surge um software que colhe todas estas informações e cria automaticamente para você um arquivo de Documentação explicando tudinho sobre cada método.
O nome do programa é: NDoc
E pode ser obtido em: http://ndoc.sourceforge.net/

Em breve preparo um tutorial de como utiliza-lo.
Um grande abraço galera!