E

GERANDO DOCUMENTAÇÃO
NO VISUAL STUDIO

OBJETIVOS

• Apresentar a ferramenta de geração de documentação do

Visual Studio.NET.
• Apresentar os comentários de documentação em XML.
• Entender as tags da documentação em XML e seu uso.
• Permitir a geração de arquivos de documentação em HTML
e XML.
 Apêndice E Gerando Documentação no Visual Studio E-31

Resumo
E.1 Introdução
E.2 Comentários da documentação
E.3 Documentando o código-fonte do C#
E.4 Criando páginas Web de comentários
E.5 Criando arquivos de documentação em XML

Resumo • Terminologia

E.1 Introdução
Um único programador pode implementar a maioria dos programas deste livro. Entretanto, o software comercial é mais
complexo, e cada projeto quase sempre requer o talento de diversos programadores. Nesses projetos, a comunicação entre os
programadores é uma necessidade. Quando um programador escreve código de uma classe, os demais integrantes do grupo
devem entender como a classe opera. Por esse motivo, cada programador deve documentar as informações específicas de uma
classe, como o papel da classe em um sistema, a funcionalidade que cada método fornece para a classe e a finalidade de cada
variável de classe. Essa documentação ajuda todos os programadores a entender como as classes podem operar entre elas e
facilita a modificação, o uso e a extensão de cada classe.
Para facilitar a criação da documentação para um projeto, o Visual Studio .NET fornece a ferramenta de documenta-
ção em XML. Essa ferramenta converte as principais informações em código-fonte — como os membros da classe, a hierar-
quia à qual a classe pertence e todas as outras observações gerais que o programador quiser documentar — para o formato
HTML1 ou XML2. O programador especifica as observações gerais a serem documentadas colocando-as em regiões especiais
do código, chamadas de comentários da documentação em XML.
Neste apêndice apresentamos as capacidades de documentação do Visual Studio .NET. Começamos discutindo o for-
mato e a estrutura dos comentários da documentação XML que a ferramenta de geração de documentação usa para criar os
arquivos de documentação. Em seguida mostramos como gerar a documentação por meio de um exemplo do LIVE-CODE.
Recomendamos a leitura dos capítulos 8 a 10 antes de ler este apêndice, porque os exemplos apresentados aqui se relacionam
aos exemplos daqueles capítulos.

E.2 Comentários da documentação

Antes que a ferramenta de geração de documentação do Visual Studio gere arquivos de documentação, o programador deve
inserir os comentários da documentação em XML nos arquivos de origem. Esses comentários contêm as informações que os
programadores desejam documentar. A ferramenta de geração de documentação reconhece apenas os comentários de uma
única linha que começam com três barras (///). Um exemplo de um comentário de documentação simples seria:
/// <summary>
/// isto é um comentário
/// </summary>

A primeira linha desse comentário inicia o elemento summary, a segunda linha define o texto que o elemento summary
contém, e a terceira linha fecha o elemento summary. Como discutiremos mais tarde neste texto, a ferramenta de documentação
só documenta o texto que está entre essas tags summary. Todos os comentários de declaração XML (excluindo as três barras)
devem conter XML bem-formada. Assim como os comentários gerais, o compilador não converte os comentários de documen-
tação para a MSIL (Microsoft Intermediate Language), para que elas não se tornem “parte” do programa.

1. O HTML é discutido nos apêndices I e J.

2. O XML é discutido no Capítulo 18.
E-32 C# — Como Programar

Como a ferramenta de documentação cria arquivos XML, os comentários da documentação podem conter determinados
tipos de marcas, como as tags HTML e o conteúdo personalizado XML. Por exemplo, o comentário de documentação
/// <summary>
/// Ordena um array de inteiros usando o algoritmo <em>MySort</em>
/// </summary>

contém as tags HTML <em> e </em>. Nos arquivos HTML gerados, MySort aparece como texto enfatizado (normalmente
em itálico).

E.3 Documentando o código-fonte do C#

As figuras E.1, E.2 e E.3 apresentam uma versão modificada das classes Point, Circle e CircleTest da Seção 9.4, a
qual contém os comentários de documentação em XML. No texto após o exemplo, discutimos cada elemento do XML que é
usado nos comentários da documentação. Na Seção E.4 discutimos como a ferramenta de documentação pode gerar a docu-
mentação em XML com base nesse arquivo.

1 // Fig. E.1: Point.cs

2 // A classe Point mantém uma coordenada X e uma Y.
3
4 using System;
5
6 namespace CircleTest
7 {
8 /// <summary>
9 /// A classe <c><b>Point</b></c> define um ponto como um par
10 /// de coordenadas x e y.
11 /// </summary>
12 public class Point
13 {
14 /// <summary>
15 /// Este número privado de <c><b>Point</b></c>
16 /// representa a coordenada x.
17 /// </summary>
18 /// <returns> A coordenada x de um inteiro.</returns>
19 private int x;
20
21 /// <summary>
22 /// Este membro privado de <c><b>Point</b></c>
23 /// representa a coordenada x.
24 /// </summary>
25 /// <returns> A coordenada y como um inteiro.</returns>
26 private int y;
27
28 /// <summary>
29 /// Construtor default da classe <c><b>Point</b></c>.
30 /// </summary>
31 /// <remarks>
32 /// Define as propriedades <c><b>X</b></c> e <c><b>Y</b></c> como 0.
33 /// </remarks>
34 public Point()
35 {
36 // a chamada implícita ao construtor de classe-base ocorre aqui
37 }
38
39 /// <summary>

Figura E.1 Point marcada com comentários em XML. (Parte 1 de 3.)

 Apêndice E Gerando Documentação no Visual Studio E-33

40 /// O construtor de <c><b>Point</b></c> que aceita dois

41 /// inteiros que representam as coordenadas x e
42 /// y do ponto.
43 /// </summary>
44 /// <remarks>
45 /// Usa as propriedades <c><b>X</b></c> e <c><b>Y</b></c>
46 /// para definir as coordenadas do ponto,
47 /// <em>não</em> os membros privados <c><b>x</b></c>.
48 /// e <c><b>y</b></c>.
49 /// </remarks>
50 /// <param name=x”Value”>
51 /// A coordenada x do círculo
52 /// </param>
53 /// <param name=”yValue”>
54 /// A coordenada y do círculo.
55 /// </param>
56 public Point( int xValue, int yValue )
57 {
58 // a chamada implícita ao construtor de classe-base ocorre aqui
59 X = xValue;
60 Y = yValue;
61 }
62
63 /// <summary>
64 /// Fornece o acesso get e set ao membro
65 /// <c><b>x</b></c>.
66 /// </summary>
67 /// <value>
68 /// <c><b>X</b></c> acessa o valor do
69 /// <c><b>x</b></c> membro de dado
70 /// </value>
71 public int X
72 {
73 get
74 {
75 return x;
76 }
77
78 set
79 {
80 x = value;
81 }
82 }
83
84 /// <summary>
85 /// Fornece o acesso get e set ao membro
86 /// <c><b>y</b></c>.
87 /// </summary>
88 /// <value>
89 /// <c><b>Y</b></c> acessa o valor do
90 /// <c><b>y</b></c> membro de dado
91 /// </value>
92 public int Y
93 {
94 get
95 {
96 return y;
97 }

Figura E.1 Point marcada com comentários em XML. (Parte 2 de 3.)

E-34 C# — Como Programar

98
99 set
100 {
101 y = value;
102 }
103 }
104
105 /// <summary>
106 /// Converte o <c><b>Point</b></c> para o
107 /// formato. <b>string</b>
108 /// </summary>
109 /// <returns>
110 /// Retorna uma string no formato:
111 /// [coordenada x, coordenada y].
112 /// </returns>
113 public override string ToString()
114 {
115 return “[” + X + “, ” + Y + “]”;
116 }
117
118 } // fim da classe Point
119 }

Figura E.1 Point marcada com comentários em XML. (Parte 3 de 3.)

1 // Fig. E.2: Circle.cs

2 // A classe Circle herda de Point.
3
4 using System;
5
6 namespace CircleTest
7 {
8 /// <summary>
9 /// A classe <c><b>Circle</b</c> herda da classe
10 /// <c><b>Point</b></c>. Ela tem um membro adicional para
11 /// representar o raio, uma propriedade que fornece acesso
12 /// a ele e o método <c><b>Area</b></c> para calcular a área
13 /// do círculo.
14 /// </summary>
15 public class Circle : Point
16 {
17 /// <summary>
18 /// Este membro privado de <c><b>Circle</b></c>
19 /// representa o raio.
20 /// </summary>
21 private double radius;
22
23 /// <summary>
24 /// O construtor padrão da classe <c><b>Circle</b></c>.
25 /// </summary>
26 /// <remarks>
27 /// Define o raio como 0.
28 /// </remarks>
29 public Circle()
30 {
31 // a chamada implícita ao construtor da classe-base ocorre aqui
Figura E.2 A classe Circle marcada com comentários em XML. (Parte 1 de 4.)
 Apêndice E Gerando Documentação no Visual Studio E-35

32 }
33
34 /// <summary>
35 /// Construtor de <c>Circle</c> que aceita dois inteiros
36 /// que representam as coordenadas x e y do círculo
37 /// e um <b>double</b> que representa o raio.
38 /// </summary>
39 /// <remarks>
40 /// Usa a propriedade <c><b>Radius</b></c> para definir o raio
41 /// do círculo, <em>não</em> o membro privado
42 /// <c><b>radius</b></c>.
43 /// </remarks>
44 /// <param name=”xValue”>
45 /// A coordenada x do círculo
46 /// </param>
47 /// <param name=”yValue”>
48 /// A coordenada y do círculo.
49 /// </param>
50 /// <param name=”radiusValue”>
51 /// O raio do círculo.
52 /// </param>
53 public Circle( int xValue, int yValue, double radiusValue )
54 : base( xValue, yValue )
55 {
56 Radius = radiusValue;
57 }
58
59 /// <summary>
60 /// Fornece o acesso get e set ao membro
61 /// <c><b>raio</b></c>.
62 /// </summary>
63 /// <remarks>
64 /// O método <c><b>set</b></c> garante
65 /// que <c><b>raio</b></c>
66 /// <em>não</em> está definido como um
67 /// número negativo.
68 /// </remarks>
69 /// <value>
70 /// <c><b>Raio</b></c> acessa o valor do
71 /// membro de dado <c><b>raio</b></c>.
72 /// </value>
73 public double Radius
74 {
75 get
76 {
77 return radius;
78 }
79
80 set
81 {
82 if ( value >= 0 )
83 radius = value;
84 }
85 }
86
87 /// <summary>
88 /// Calcula o diâmetro do círculo.
89 /// </summary>

Figura E.2 A classe Circle marcada com comentários em XML. (Parte 2 de 3.)
E-36 C# — Como Programar

90 /// <returns>
91 /// Retorna o diâmetro do círculo.
92 /// </returns>
93 public double Diameter()
94 {
95 return Radius * 2;
96 }
97
98 /// <summary>
99 /// Calcula a circunferência do círculo.
100 /// </summary>
101 /// <remarks>
102 /// Usa a constante <c><b>Math.PI</b></c>
103 /// <see cref=”System.Math.PI”/>
104 /// </remarks>
105 /// <returns>
106 /// Retorna a circunferência do círculo.
107 /// </returns>
108 public double Circumference()
109 {
110 return Math.PI * Diameter();
111 }
112
113 /// <summary>
114 /// Calcula a área do círculo.
115 /// </summary>
116 /// <remarks>
117 /// Usa a constante <c><b>Math.PI</b></c>
118 /// <see cref=”System.Math.PI”/>
119 /// </remarks>
120 /// <returns>
121 /// Retorna a área do círculo.
122 /// </returns>
123 public double Area()
124 {
125 return Math.PI * Math.Pow( Radius, 2 );
126 }
127
128 /// <summary>
129 /// converte o <c><b>Circle</b></c> no
130 /// formato <b>string</b>.
131 /// </summary>
132 /// <remarks>
133 /// Substitui o método <c><b>ToString</b></c> da classe-base.
134 /// <see cref=”CircleTest.Point.ToString”/>
135 /// </remarks>
136 /// <returns>
137 /// Retorna uma string que inclui o centro do
138 /// círculo e seu raio.
139 /// </returns>
140 public override string ToString()
141 {
142 return “Center = ” + base.ToString() +
143 “; Radius = ” + Radius;
144 }
145
146 } // fim da classe Circle
147 }

Figura E.2 A classe Circle marcada com comentários em XML. (Parte 3 de 3.)
 Apêndice E Gerando Documentação no Visual Studio E-37

1 // Fig. E.3: CircleTest.cs

2 // Manipulando um objeto Circle.
3
4 using System;
5 using System.Windows.Forms;
6
7 namespace CircleTest
8 {
9 /// <summary>
10 /// A classe <c><b>CircleTest</b></c> testa as
11 /// classes <c><b>Point</b></c> e <c><b>Point</b></c>.
12 /// </summary>
13 class CircleTest
14 {
15 /// <summary>
16 /// Ponto de entrada do aplicativo.
17 /// </summary>
18 /// <remarks>
19 /// Neste aplicativo todos os argumentos de linha de comando
20 /// são ignorados.
21 /// </remarks>
22 /// <param name=”args”>
23 /// Argumentos opcionais de Main.
24 /// </param>
25 static void Main( string[] args )
26 {
27 Circle circle = new Circle( 37, 43, 2.5 );
28
29 // anexa as propriedades de Circle à saída
30 string output = “X coordinate is ” + circle.X + “\n” +
31 “Y coordinate is ” + circle.Y + “\n” +
32 “Radius is ” + circle.Radius;
33
34 // define as novas coordenadas e o raio
35 circle.X = 2;
36 circle.Y = 2;
37 circle.Radius = 4.25;
38
39 output += “\n\n” +
40 “The new location and radius of circle are ” +
41 “\n” + circle + “\n”;
42
43 // exibe o diâmetro de Circle
44 output += “Diameter is ” +
45 String.Format( “{0:F}”, circle.Diameter() ) + “\n”;
46
47 // exibe a circunferência de Circle
48 output += “Circumference is ” +
49 String.Format( “{0:F}”, circle.Circumference() ) + “\n”;
50
51 // exibe a área de Circle
52 output += “Area is ” +
53 String.Format( “{0:F}”, circle.Area() );
54
55 MessageBox.Show( output, “Demonstrating Class Circle” );
56
57 } // fim do método Main
58

Figura E.3 A classe CircleTest marcada com comentários em XML. (Parte 1 de 2.)
E-38 C# — Como Programar

59 } // fim da classe CircleTest

60 }

Figura E.3 A classe CircleTest marcada com comentários em XML. (Parte 2 de 2.)

Os comentários da documentação em XML podem ser colocados antes de uma definição de classe, antes de uma
definição de interface, antes de um construtor ou de um membro (ou seja, de uma variável de instância ou referência). O
programador pode colocar uma descrição (ou seja, uma finalidade) da classe no elemento summary, que pode conter
quantas linhas forem necessárias para fornecer uma descrição do método de classe, das propriedades, dos membros etc.
Como veremos na próxima seção, todo conteúdo colocado no elemento summary será marcado em uma coluna (rotulada
como Descrição) de uma tabela HTML. Um exemplo de um summary é mostrado nas linhas 8 a 11 da Figura E.1 para
fornecer uma descrição da classe Point (também usamos essas tags na Seção E.2, quando apresentamos os comentários
da documentação).
Dois elementos normalmente usados para descrever métodos são returns e param. O elemento returns contém
as informações sobre o valor de retorno, como ilustram as linhas 109 a 112 da Figura E.1. O método ToString de Point
retorna uma string formatada que tem o par de coordenadas x-y do ponto. Da mesma maneira, o elemento param contém
as informações sobre os parâmetros de um método. Por exemplo, as linhas 50 a 55 da Figura E.1 associam um elemento
param a uma variável x e outro elemento param a uma variável y.
Usamos os elementos c XML para marcar as regiões do código em seus comentários. A linha 102 da Figura E.2 mos-
tra o uso do elemento c para especificar que Math.PI deve ser marcado como código na documentação resultante. Observe
que o elemento c contém o elemento b que coloca Math.PI no tipo negrito dentro da página Web.
A tag remarks permite que os programadores documentem todas as informações “diversas” ou os comentários deta-
lhados. Por exemplo, as linhas 116 a 119 da Figura E.2 documentam que o método Area usa a constante Math.PI.
A tag see (linhas 103, 118 e 134 da Figura E.2) referencia outra classe ou membro (método, constante, propriedade
etc.). Qualquer membro pode ser referenciado usando o nome totalmente qualificado (por exemplo, System.Console.Re
adLine). A tag value (linhas 67 a 70 e 88 a 91 da Figura E.1 e as linhas 69 a 72 da Figura E.2) é usada para descrever as
propriedades. Esses comentários não têm efeito sobre as páginas Web que podem ser geradas.
Para obter outras informações sobre essas tags e outras tags a ser usadas visite este URL:

ms-help://MS.VSCC/MS.MSDNVS/csref/html/
vclrftagsfordocumentationcomments.htm

E.4 Criando páginas Web de comentários

Nesta seção mostramos como o Visual Studio .NET pode criar a documentação no formato de página Web com base no
código-fonte que contém os comentários da documentação em XML. Demonstramos esse recurso no projeto que contém as
classes das Figuras E.1, E.2 e E.3. Após abrir esse projeto, selecione Tools >Build Comment Web Pages (Figura E.4). A
janela Build Comment Web Pages aparece e permite que o desenvolvedor especifique os projetos que contêm os arquivos
que o Visual Studio .NET deve documentar (Figura E.5). Se o desenvolvedor selecionar Build for entire Solution, o Visual
 Apêndice E Gerando Documentação no Visual Studio E-39

Figura E.4 Selecionando Build Comment Web Pages no menu Tools.

Figura E.5 Salvando um documento em um arquivo.

Studio .NET documentará todos os arquivos da solução atual. Se selecionar Build for selected Projects, o Visual Studio
.NET documentará apenas os arquivos do projeto que o desenvolvedor especificar. Além disso, pode-se especificar o diretório
no qual o Visual Studio .NET deve armazenar o conteúdo HTML gerado. Se o desenvolvedor selecionar Add to Favorites,
o Visual Studio .NET marcará esse conteúdo no menu Favorites do Internet Explorer.
Pressione OK para gerar o conteúdo HTML. O Visual Studio cria e exibe imediatamente a documentação usando uma
folha de estilos. Em nosso exemplo, o usuário pode visualizar a comunicação das classes Circle, CircleTest e Point
selecionando a classe desejada na coluna mais à esquerda. A Figura E.6 mostra a documentação da classe Circle.
Observe que todos os nomes de membros e os elementos summary da Figura E.2 foram formatados e colocados nas
colunas Members e Description, respectivamente (Figura E.6). A seleção de um item da coluna Members abre uma
página HTML associada àquele item. A Figura E.7 mostra a página HTML associada ao método Area da classe Circle.
Observe que as tags returns da Figura E.2 das linhas 120 a 122 marcam o texto que é documentado à medida que o texto
é colocado na coluna Description.
E-40 C# — Como Programar

Figura E.6 A documentação em XHTML da classe Circle.

Figura E.7 A documentação em XHTML do método Area da classe Circle.

E.5 Criando arquivos de documentação em XML

Nesta seção discutiremos como gerar um arquivo de documentação XML que contenha todos os elementos dos comentários
do código-fonte. Em seguida, um aplicativo lerá esse arquivo e criará a documentação personalizada com base nessas infor-
mações.
 Apêndice E Gerando Documentação no Visual Studio E-41

Para criar um arquivo de documentação XML para um projeto, dê um clique com o botão direito do mouse no projeto
no Solution Explorer e selecione Properties. Selecione a pasta Configuration e, em seguida, a guia Build. Altere a
propriedade XML Documentation File para o nome do arquivo que armazenará a documentação XML e dê um clique
em OK. Se esse arquivo não existir, o Visual Studio criará o arquivo e o colocará no diretório bin/Debug do projeto atual.
Selecione Build > Build Solution para compilar o projeto e criar o documento XML. A Figura E.8 mostra o documento
XML gerado para o exemplo da Figura E.1 até a Figura E.3.

1 <?xml version=”1.0”?>
2 <doc>
3 <assembly>
4 <name>Point-Circle</name>
5 </assembly>
6 <members>
7
8 <member name=“T:CircleTest.Circle”>
9 <summary>
10 Class <c><b>Circle</b></c> inherits from class
11 <c><b>Point</b></c>. It has an additional member to
12 represent the radius, a property that provides
13 accessto it and method <c><b>Area</b></c> to
14 compute the area of the circle.
15 </summary>
16 </member>
17
18 <member name=“T:CircleTest.Point”>
19 <summary>
20 Class <c><b>Point</b></c> defines a point as a pair
21 of x and y coordinates.
22 </summary>
23 </member>
24
25 <member name=“F:CircleTest.Point.xCoordinate”>
26 <summary>
27 This protected member of <c><b>Point</b></c>
28 represents the x coordinate.
29 </summary>
30 <returns> The x coordinate as an integer.</returns>
31 </member>
32
33 <member name=“F:CircleTest.Point.yCoordinate”>
34 <summary>
35 This protected member of <c><b>Point</b></c>
36 represents the x coordinate.
37 </summary>
38 <returns> The y coordinate as an integer.</returns>
39 </member>
40
41 <member name=“M:CircleTest.Point.#ctor”>
42 <summary>
43 Default constructor for class <c><b>Point</b></c>.
44 </summary>
45 <remarks>
46 Sets properties <c><b>X</b></c> and <c><b>Y</b></c> to 0.
47 </remarks>
48 </member>
49
50 <member name=
Figura E.8 A documentação em XML gerada pelo Visual Studio .NET. (Parte 1 de 5.)
E-42 C# — Como Programar

51 “M:CircleTest.Point.#ctor(System.Int32,System.Int32)”>
52 <summary>
53 Constructor for <c><b>Point</b></c>
54 that accepts two integers
55 that represent the x and y coordinates of the point.
56 </summary>
57 <remarks>
58 Uses <c><b>X</b></c> and <c><b>Y</b></c>
59 properties to set the coordinates of the point,
60 <em>not</em> private members <c><b>x</b></c>
61 and <c><b>y</b></c>.
62 </remarks>
63 <param name=“xValue”>
64 The x coordinate of the circle
65 </param>
66 <param name=“yValue”>
67 The y coordinate of the circle.
68 </param>
69 </member>
70
71 <member name=“M:CircleTest.Point.ToString”>
72 <summary>
73 Converts the <c><b>Point</b></c> to
74 <b>string</b> format.
75 </summary>
76 <returns>
77 Returns a string in format:
78 [x coordinate, y coordinate].
79 </returns>
80 </member>
81
82 <member name=“P:CircleTest.Point.X”>
83 <summary>
84 Provides get and set access to member
85 <c><b>x</b></c>.
86 </summary>
87 <value>
88 <c><b>X</b></c> accesses the value of the
89 <c><b>x</b></c> data member.
90 </value>
91 </member>
92
93 <member name=“P:CircleTest.Point.Y”>
94 <summary>
95 Provides get and set access to member
96 <c><b>y</b></c>.
97 </summary>
98 <value>
99 <c><b>Y</b></c> accesses the value of the
100 <c><b>y</b></c> data member.
101 </value>
102 </member>
103
104 <member name=“F:CircleTest.Circle.radius”>
105 <summary>
106 This private member of <c><b>Circle</b></c>
107 represents the radius.
108 </summary>
Figura E.8 A documentação em XML gerada pelo Visual Studio .NET. (Parte 2 de 5.)
 Apêndice E Gerando Documentação no Visual Studio E-43

109 </member>
110
111 <member name=“M:CircleTest.Circle.#ctor”>
112 <summary>
113 Default constructor for class <c><b>Circle</b></c>.
114 </summary>
115 <remarks>
116 Sets the radius to 0.
117 </remarks>
118 </member>
119
120 <member name=“M:CircleTest.Circle.#ctor(System.Int32,
121 System.Int32,System.Double)”>
122 <summary>
123 Constructor for <c><b>Circle<b></c> that accepts two
124 integersthat represent the x and y coordinates of the
125 circle and a <b>double</b> that represents the radius.
126 </summary>
127 <remarks>
128 Uses property <c><b>Radius</b></c> to set the radius
129 of the circle, <em>not</em> private member
130 <c><b>radius</b></c>.
131 </remarks>
132 <param name=“xValue”>
133 The x coordinate of the circle
134 </param>
135 <param name=“yValue”>
136 The y coordinate of the circle.
137 </param>
138 <param name=“radiusValue”>
139 The radius of the circle.
140 </param>
141 </member>
142
143 <member name=“M:CircleTest.Circle.Diameter”>
144 <summary>
145 Computes the diameter of the circle.
146 </summary>
147 <returns>
148 Returns the diameter of the circle.
149 </returns>
150 </member>
151
152 <member name=“M:CircleTest.Circle.Circumference”>
153 <summary>
154 Computes the circumference of the circle.
155 </summary>
156 <remarks>
157 Uses constant <c><b>Math.PI</b></c>
158 <see cref=“F:System.Math.PI”/>
159 </remarks>
160 <returns>
161 Returns the circumference of the circle.
162 </returns>
163 </member>
164
165 <member name=“M:CircleTest.Circle.Area”>
166 <summary>
Figura E.8 A documentação em XML gerada pelo Visual Studio .NET. (Parte 3 de 5.)
E-44 C# — Como Programar

167 Computes the area of the circle.

168 </summary>
169 <remarks>
170 Uses constant <c><b>Math.PI</b></c>
171 <see cref=“F:System.Math.PI”/>
172 </remarks>
173 <returns>
174 Returns the area of the circle.
175 </returns>
176 </member>
177
178 <member name=“M:CircleTest.Circle.ToString”>
179 <summary>
180 Converts the <c><b>Circle</b></c> to
181 <b>string</b> format.
182 </summary>
183 <remarks>
184 Overrides <c><b>ToString</b></c> method of base class.
185 <see cref=“!:CircleTest.Point.ToString”/>
186 </remarks>
187 <returns>
188 Returns a string that includes the center of the
189 circle and its radius.
190 </returns>
191 </member>
192
193 <member name=“P:CircleTest.Circle.Radius”>
194 <summary>
195 Provides get and set access to member
196 <c><b>radius</b></c>.
197 </summary>
198 <remarks>
199 The <c><b>set</b></c> method
200 ensures that <c><b>radius</b></c>
201 is <em>not</em> set to a
202 negative number.
203 </remarks>
204 <value>
205 <c><b>Radius</b></c> accesses the value of the
206 <c><b>radius</b></c> data member.
207 </value>
208 </member>
209
210 <member name=“T:CircleTest.CircleTest”>
211 <summary>
212 Class <c><b>CircleTest</b></c> inherits from class
213 tests the <c><b>Point</b></c> and
214 <c><b>Point</b></c> classes.
215 </summary>
216 </member>
217
218 <member name=“M:CircleTest.CircleTest.Main(System.String[])”>
219 <summary>
220 Entry point of application.
221 </summary>
222 <remarks>
223 In this application all command-line arguments
224 are ignored.
Figura E.8 A documentação em XML gerada pelo Visual Studio .NET. (Parte 4 de 5.)
 Apêndice E Gerando Documentação no Visual Studio E-45

225 </remarks>
226 <param name=“args”>
227 Optional arguments to Main.
228 </param>
229 </member>
230
231 </members>
232 </doc>

Figura E.8 A documentação em XML gerada pelo Visual Studio .NET. (Parte 5 de 5.)

Observe que apenas os membros de classe são incluídos no arquivo XML gerado. Cada membro de classe tem um
elemento member que inclui todos os comentários em XML daquele membro. Por exemplo, as linhas 50 a 69 definem um
elemento member que contém as informações sobre o construtor de dois argumentos Point. O atributo name de uma tag
member é uma string que contém as informações sobre o nome e o tipo do membro. O tipo é especificado por uma letra
maiúscula: M de método, P de propriedade (ou indexador), E de evento e T de tipo (ou seja, classe). Para obter uma listagem
completa dessas abreviações selecione Help > Index e, em seguida, localize o tópico processing XML files in C#. Na
Figura E.8, a linha 51 contém o valor do atributo name e um M como a primeira letra, indicando que a linha 51 declara um mé-
todo (lembre-se de que um construtor é um método especializado). Um sinal de dois-pontos e o nome completo do método são
mostrados. Neste exemplo, o nome do método é CircleTest.Point.#ctor(System.Int32,System.Int32).
Como esse é um construtor, a string #ctor é usada no nome totalmente qualificado. Esse construtor assume dois argumentos
int — os parênteses após o nome de cada membro especificam o tipo daquele membro.

Resumo
• Os programadores devem documentar as informações específicas de uma classe, como o papel da classe em um sistema, a funciona-
lidade que cada método fornece para a classe e a finalidade da variável de cada classe.
• A documentação ajuda todos os programadores a entender como as classes podem interoperar e facilita a modificação, o uso e a ex-
tensão de cada classe.
• O Visual Studio .NET fornece a ferramenta de documentação em XML. Essa ferramenta converte as principais informações do código
— como os membros da classe, a hierarquia à qual a classe pertence e todas as outras observações gerais que o programador deseja
documentar — no formato HTML ou XML.
• O programador especifica as observações gerais a serem documentadas colocando-as em regiões especiais do código, as quais são
chamadas de comentários da documentação em XML.
• A ferramenta de geração de documentação reconhece apenas os comentários de uma única linha que começam com três barras (///).
• O compilador não converte os comentários da documentação em MSIL (Microsoft Intermediate Language).
• O programador pode colocar uma descrição (ou seja, a finalidade) da classe entre as tags summary.
• O elemento returns contém as informações sobre o valor de retorno. Da mesma maneira, o elemento param contém as informa-
ções sobre os parâmetros de um método.
• O elemento c marca as regiões de código nos comentários.
• A tag remarks permite que os programadores documentem todas as informações “diversas” ou os comentários detalhados relacio-
nados a um membro.
• A tag see é usada para referenciar outro membro (método, constante, propriedade etc.).

Terminologia
/// (comentário de documentação) comentário da documentação XML
atributo name do elemento member construtor
Build Comment Web Pages criando a documentação em XML
código-fonte declaração de método
coluna Documentation definição de classe
coluna Members definição de interface
E-46 C# — Como Programar

diretório elemento value

documentação folha de estilos
elemento c HTML
elemento member membro
elemento para parâmetros
elemento param propriedade
elemento remarks referência
elemento returns tag
elemento see valor de retorno
elemento summary variável de instância