E

GERANDO DOCUMENTAO
NO VISUAL STUDIO

OBJETIVOS

Apresentar a ferramenta de gerao de documentao do

Visual Studio.NET.
Apresentar os comentrios de documentao em XML.
Entender as tags da documentao em XML e seu uso.
Permitir a gerao de arquivos de documentao em HTML
e XML.
 Apndice E Gerando Documentao no Visual Studio E-31

Resumo
E.1 Introduo
E.2 Comentrios da documentao
E.3 Documentando o cdigo-fonte do C#
E.4 Criando pginas Web de comentrios
E.5 Criando arquivos de documentao em XML

Resumo Terminologia

E.1 Introduo
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 comunicao entre os
programadores uma necessidade. Quando um programador escreve cdigo de uma classe, os demais integrantes do grupo
devem entender como a classe opera. Por esse motivo, cada programador deve documentar as informaes especficas de uma
classe, como o papel da classe em um sistema, a funcionalidade que cada mtodo fornece para a classe e a finalidade de cada
varivel de classe. Essa documentao ajuda todos os programadores a entender como as classes podem operar entre elas e
facilita a modificao, o uso e a extenso de cada classe.
Para facilitar a criao da documentao para um projeto, o Visual Studio .NET fornece a ferramenta de documenta-
o em XML. Essa ferramenta converte as principais informaes em cdigo-fonte como os membros da classe, a hierar-
quia qual a classe pertence e todas as outras observaes gerais que o programador quiser documentar para o formato
HTML1 ou XML2. O programador especifica as observaes gerais a serem documentadas colocando-as em regies especiais
do cdigo, chamadas de comentrios da documentao em XML.
Neste apndice apresentamos as capacidades de documentao do Visual Studio .NET. Comeamos discutindo o for-
mato e a estrutura dos comentrios da documentao XML que a ferramenta de gerao de documentao usa para criar os
arquivos de documentao. Em seguida mostramos como gerar a documentao por meio de um exemplo do LIVE-CODE.
Recomendamos a leitura dos captulos 8 a 10 antes de ler este apndice, porque os exemplos apresentados aqui se relacionam
aos exemplos daqueles captulos.

E.2 Comentrios da documentao

Antes que a ferramenta de gerao de documentao do Visual Studio gere arquivos de documentao, o programador deve
inserir os comentrios da documentao em XML nos arquivos de origem. Esses comentrios contm as informaes que os
programadores desejam documentar. A ferramenta de gerao de documentao reconhece apenas os comentrios de uma
nica linha que comeam com trs barras (///). Um exemplo de um comentrio de documentao simples seria:
/// <summary>
/// isto um comentrio
/// </summary>

A primeira linha desse comentrio inicia o elemento summary, a segunda linha define o texto que o elemento summary
contm, e a terceira linha fecha o elemento summary. Como discutiremos mais tarde neste texto, a ferramenta de documentao
s documenta o texto que est entre essas tags summary. Todos os comentrios de declarao XML (excluindo as trs barras)
devem conter XML bem-formada. Assim como os comentrios gerais, o compilador no converte os comentrios de documen-
tao para a MSIL (Microsoft Intermediate Language), para que elas no se tornem parte do programa.

1. O HTML discutido nos apndices I e J.

2. O XML discutido no Captulo 18.
E-32 C# Como Programar

Como a ferramenta de documentao cria arquivos XML, os comentrios da documentao podem conter determinados
tipos de marcas, como as tags HTML e o contedo personalizado XML. Por exemplo, o comentrio de documentao
/// <summary>
/// Ordena um array de inteiros usando o algoritmo <em>MySort</em>
/// </summary>

contm as tags HTML <em> e </em>. Nos arquivos HTML gerados, MySort aparece como texto enfatizado (normalmente
em itlico).

E.3 Documentando o cdigo-fonte do C#

As figuras E.1, E.2 e E.3 apresentam uma verso modificada das classes Point, Circle e CircleTest da Seo 9.4, a
qual contm os comentrios de documentao em XML. No texto aps o exemplo, discutimos cada elemento do XML que
usado nos comentrios da documentao. Na Seo E.4 discutimos como a ferramenta de documentao pode gerar a docu-
mentao em XML com base nesse arquivo.

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

2 // A classe Point mantm 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 nmero 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 implcita ao construtor de classe-base ocorre aqui
37 }
38
39 /// <summary>

Figura E.1 Point marcada com comentrios em XML. (Parte 1 de 3.)

 Apndice E Gerando Documentao 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>no</em> os membros privados <c><b>x</b></c>.
48 /// e <c><b>y</b></c>.
49 /// </remarks>
50 /// <param name=xValue>
51 /// A coordenada x do crculo
52 /// </param>
53 /// <param name=yValue>
54 /// A coordenada y do crculo.
55 /// </param>
56 public Point( int xValue, int yValue )
57 {
58 // a chamada implcita 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 comentrios 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 comentrios 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 mtodo <c><b>Area</b></c> para calcular a rea
13 /// do crculo.
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 padro 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 implcita ao construtor da classe-base ocorre aqui
Figura E.2 A classe Circle marcada com comentrios em XML. (Parte 1 de 4.)
 Apndice E Gerando Documentao 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 crculo
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 crculo, <em>no</em> o membro privado
42 /// <c><b>radius</b></c>.
43 /// </remarks>
44 /// <param name=xValue>
45 /// A coordenada x do crculo
46 /// </param>
47 /// <param name=yValue>
48 /// A coordenada y do crculo.
49 /// </param>
50 /// <param name=radiusValue>
51 /// O raio do crculo.
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 mtodo <c><b>set</b></c> garante
65 /// que <c><b>raio</b></c>
66 /// <em>no</em> est definido como um
67 /// nmero 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 dimetro do crculo.
89 /// </summary>

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

90 /// <returns>
91 /// Retorna o dimetro do crculo.
92 /// </returns>
93 public double Diameter()
94 {
95 return Radius * 2;
96 }
97
98 /// <summary>
99 /// Calcula a circunferncia do crculo.
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 circunferncia do crculo.
107 /// </returns>
108 public double Circumference()
109 {
110 return Math.PI * Diameter();
111 }
112
113 /// <summary>
114 /// Calcula a rea do crculo.
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 crculo.
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 mtodo <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 /// crculo 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 comentrios em XML. (Parte 3 de 3.)
 Apndice E Gerando Documentao 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 /// so 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 sada
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 dimetro de Circle
44 output += Diameter is +
45 String.Format( {0:F}, circle.Diameter() ) + \n;
46
47 // exibe a circunferncia 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 mtodo Main
58

Figura E.3 A classe CircleTest marcada com comentrios 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 comentrios em XML. (Parte 2 de 2.)

Os comentrios da documentao em XML podem ser colocados antes de uma definio de classe, antes de uma
definio de interface, antes de um construtor ou de um membro (ou seja, de uma varivel de instncia ou referncia). O
programador pode colocar uma descrio (ou seja, uma finalidade) da classe no elemento summary, que pode conter
quantas linhas forem necessrias para fornecer uma descrio do mtodo de classe, das propriedades, dos membros etc.
Como veremos na prxima seo, todo contedo colocado no elemento summary ser marcado em uma coluna (rotulada
como Descrio) de uma tabela HTML. Um exemplo de um summary mostrado nas linhas 8 a 11 da Figura E.1 para
fornecer uma descrio da classe Point (tambm usamos essas tags na Seo E.2, quando apresentamos os comentrios
da documentao).
Dois elementos normalmente usados para descrever mtodos so returns e param. O elemento returns contm
as informaes sobre o valor de retorno, como ilustram as linhas 109 a 112 da Figura E.1. O mtodo ToString de Point
retorna uma string formatada que tem o par de coordenadas x-y do ponto. Da mesma maneira, o elemento param contm
as informaes sobre os parmetros de um mtodo. Por exemplo, as linhas 50 a 55 da Figura E.1 associam um elemento
param a uma varivel x e outro elemento param a uma varivel y.
Usamos os elementos c XML para marcar as regies do cdigo em seus comentrios. A linha 102 da Figura E.2 mos-
tra o uso do elemento c para especificar que Math.PI deve ser marcado como cdigo na documentao resultante. Observe
que o elemento c contm o elemento b que coloca Math.PI no tipo negrito dentro da pgina Web.
A tag remarks permite que os programadores documentem todas as informaes diversas ou os comentrios deta-
lhados. Por exemplo, as linhas 116 a 119 da Figura E.2 documentam que o mtodo Area usa a constante Math.PI.
A tag see (linhas 103, 118 e 134 da Figura E.2) referencia outra classe ou membro (mtodo, 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 comentrios no tm efeito sobre as pginas Web que podem ser geradas.
Para obter outras informaes 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 pginas Web de comentrios

Nesta seo mostramos como o Visual Studio .NET pode criar a documentao no formato de pgina Web com base no
cdigo-fonte que contm os comentrios da documentao em XML. Demonstramos esse recurso no projeto que contm as
classes das Figuras E.1, E.2 e E.3. Aps 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 contm os arquivos
que o Visual Studio .NET deve documentar (Figura E.5). Se o desenvolvedor selecionar Build for entire Solution, o Visual
 Apndice E Gerando Documentao 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 soluo atual. Se selecionar Build for selected Projects, o Visual Studio
.NET documentar apenas os arquivos do projeto que o desenvolvedor especificar. Alm disso, pode-se especificar o diretrio
no qual o Visual Studio .NET deve armazenar o contedo HTML gerado. Se o desenvolvedor selecionar Add to Favorites,
o Visual Studio .NET marcar esse contedo no menu Favorites do Internet Explorer.
Pressione OK para gerar o contedo HTML. O Visual Studio cria e exibe imediatamente a documentao usando uma
folha de estilos. Em nosso exemplo, o usurio pode visualizar a comunicao das classes Circle, CircleTest e Point
selecionando a classe desejada na coluna mais esquerda. A Figura E.6 mostra a documentao 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 seleo de um item da coluna Members abre uma
pgina HTML associada quele item. A Figura E.7 mostra a pgina HTML associada ao mtodo 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 documentao em XHTML da classe Circle.

Figura E.7 A documentao em XHTML do mtodo Area da classe Circle.

E.5 Criando arquivos de documentao em XML

Nesta seo discutiremos como gerar um arquivo de documentao XML que contenha todos os elementos dos comentrios
do cdigo-fonte. Em seguida, um aplicativo ler esse arquivo e criar a documentao personalizada com base nessas infor-
maes.
 Apndice E Gerando Documentao no Visual Studio E-41

Para criar um arquivo de documentao XML para um projeto, d um clique com o boto 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 documentao XML e d um clique
em OK. Se esse arquivo no existir, o Visual Studio criar o arquivo e o colocar no diretrio 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 documentao 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 documentao em XML gerada pelo Visual Studio .NET. (Parte 2 de 5.)
 Apndice E Gerando Documentao 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 documentao 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 documentao em XML gerada pelo Visual Studio .NET. (Parte 4 de 5.)
 Apndice E Gerando Documentao 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 documentao em XML gerada pelo Visual Studio .NET. (Parte 5 de 5.)

Observe que apenas os membros de classe so includos no arquivo XML gerado. Cada membro de classe tem um
elemento member que inclui todos os comentrios em XML daquele membro. Por exemplo, as linhas 50 a 69 definem um
elemento member que contm as informaes sobre o construtor de dois argumentos Point. O atributo name de uma tag
member uma string que contm as informaes sobre o nome e o tipo do membro. O tipo especificado por uma letra
maiscula: M de mtodo, P de propriedade (ou indexador), E de evento e T de tipo (ou seja, classe). Para obter uma listagem
completa dessas abreviaes selecione Help > Index e, em seguida, localize o tpico processing XML files in C#. Na
Figura E.8, a linha 51 contm 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 mtodo especializado). Um sinal de dois-pontos e o nome completo do mtodo so
mostrados. Neste exemplo, o nome do mtodo 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 parnteses aps o nome de cada membro especificam o tipo daquele membro.

Resumo
Os programadores devem documentar as informaes especficas de uma classe, como o papel da classe em um sistema, a funciona-
lidade que cada mtodo fornece para a classe e a finalidade da varivel de cada classe.
A documentao ajuda todos os programadores a entender como as classes podem interoperar e facilita a modificao, o uso e a ex-
tenso de cada classe.
O Visual Studio .NET fornece a ferramenta de documentao em XML. Essa ferramenta converte as principais informaes do cdigo
como os membros da classe, a hierarquia qual a classe pertence e todas as outras observaes gerais que o programador deseja
documentar no formato HTML ou XML.
O programador especifica as observaes gerais a serem documentadas colocando-as em regies especiais do cdigo, as quais so
chamadas de comentrios da documentao em XML.
A ferramenta de gerao de documentao reconhece apenas os comentrios de uma nica linha que comeam com trs barras (///).
O compilador no converte os comentrios da documentao em MSIL (Microsoft Intermediate Language).
O programador pode colocar uma descrio (ou seja, a finalidade) da classe entre as tags summary.
O elemento returns contm as informaes sobre o valor de retorno. Da mesma maneira, o elemento param contm as informa-
es sobre os parmetros de um mtodo.
O elemento c marca as regies de cdigo nos comentrios.
A tag remarks permite que os programadores documentem todas as informaes diversas ou os comentrios detalhados relacio-
nados a um membro.
A tag see usada para referenciar outro membro (mtodo, constante, propriedade etc.).

Terminologia
/// (comentrio de documentao) comentrio da documentao XML
atributo name do elemento member construtor
Build Comment Web Pages criando a documentao em XML
cdigo-fonte declarao de mtodo
coluna Documentation definio de classe
coluna Members definio de interface
E-46 C# Como Programar

diretrio elemento value

documentao folha de estilos
elemento c HTML
elemento member membro
elemento para parmetros
elemento param propriedade
elemento remarks referncia
elemento returns tag
elemento see valor de retorno
elemento summary varivel de instncia