GERANDO DOCUMENTAÇÃO

EGERANDO 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

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ífi cas de uma classe, como o papel da classe em um sistema, a funcionalidade que cada método fornece para a classe e a fi nalidade 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 modifi caçã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 especifi ca 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 defi ne 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.

Resumo

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

Resumo • Terminologia

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

2. O XML é discutido no Capítulo 18.

C# — Como ProgramarE-32

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 MySort

/// </summary>

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

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

As fi guras E.1, E.2 e E.3 apresentam uma versão modifi cada 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.

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

1 // Fig. E.1: Point.cs2 // A classe Point mantém uma coordenada X e uma Y.3

4 using System;5

6 namespace CircleTest7 {8 /// <summary>9 /// A classe <c>Point</c> defi ne um ponto como um par10 /// de coordenadas x e y.11 /// </summary>12 public class Point 13 {14 /// <summary>15 /// Este número privado de <c>Point</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>Point</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>Point</c>.30 /// </summary>31 /// <remarks>32 /// Defi ne as propriedades <c>X</c> e <c>Y</c> como 0.33 /// </remarks>34 public Point()35 {36 // a chamada implícita ao construtor de classe-base ocorre aqui37 }38

39 /// <summary>


40 /// O construtor de <c>Point</c> que aceita dois41 /// inteiros que representam as coordenadas x e42 /// y do ponto.43 /// </summary>44 /// <remarks>45 /// Usa as propriedades <c>X</c> e <c>Y</c>46 /// para defi nir as coordenadas do ponto,47 /// não os membros privados <c>x</c>.48 /// e <c>y</c>.49 /// </remarks>50 /// <param name=x”Value”>51 /// A coordenada x do círculo52 /// </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 aqui59 X = xValue;60 Y = yValue;61 }62

63 /// <summary>64 /// Fornece o acesso get e set ao membro65 /// <c>x</c>.66 /// </summary>67 /// <value>68 /// <c>X</c> acessa o valor do 69 /// <c>x</c> membro de dado 70 /// </value>71 public int X72 {73 get74 {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>y</c>.87 /// </summary>88 /// <value>89 /// <c>Y</c> acessa o valor do 90 /// <c>y</c> membro de dado91 /// </value>92 public int Y93 {94 get95 {96 return y;97 }



98

99 set 100 {101 y = value;102 }103 }104

105 /// <summary>106 /// Converte o <c>Point</c> para o 107 /// formato. string 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 } // fi m da classe Point119 }


1 // Fig. E.2: Circle.cs2 // A classe Circle herda de Point.3

4 using System;5

6 namespace CircleTest7 {8 /// <summary>9 /// A classe <c>Circle</b</c> herda da classe 10 /// <c>Point</c>. Ela tem um membro adicional para11 /// representar o raio, uma propriedade que fornece acesso12 /// a ele e o método <c>Area</c> para calcular a área 13 /// do círculo.14 /// </summary>15 public class Circle : Point16 {17 /// <summary>18 /// Este membro privado de <c>Circle</c> 19 /// representa o raio.20 /// </summary>21 private double radius;22

23 /// <summary>24 /// O construtor padrão da classe <c>Circle</c>.25 /// </summary>26 /// <remarks>27 /// Defi ne 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.)


32 }33

34 /// <summary>35 /// Construtor de <c>Circle</c> que aceita dois inteiros36 /// que representam as coordenadas x e y do círculo37 /// e um double que representa o raio.38 /// </summary>39 /// <remarks>40 /// Usa a propriedade <c>Radius</c> para defi nir o raio 41 /// do círculo, não o membro privado42 /// <c>radius</c>.43 /// </remarks>44 /// <param name=”xValue”>45 /// A coordenada x do círculo46 /// </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 membro61 /// <c>raio</c>.62 /// </summary>63 /// <remarks>64 /// O método <c>set</c> garante 65 /// que <c>raio</c> 66 /// não está defi nido como um67 /// número negativo.68 /// </remarks>69 /// <value>70 /// <c>Raio</c> acessa o valor do 71 /// membro de dado <c>raio</c>.72 /// </value>73 public double Radius74 {75 get76 {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>



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>Math.PI</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>Math.PI</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>Circle</c> no 130 /// formato string.131 /// </summary>132 /// <remarks>133 /// Substitui o método <c>ToString</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 } // fi m da classe Circle147 }



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

1 // Fig. E.3: CircleTest.cs2 // Manipulando um objeto Circle.3

4 using System;5 using System.Windows.Forms;6

7 namespace CircleTest8 {9 /// <summary>10 /// A classe <c>CircleTest</c> testa as11 /// classes <c>Point</c> e <c>Point</c>.12 /// </summary>13 class CircleTest14 {15 /// <summary>16 /// Ponto de entrada do aplicativo.17 /// </summary>18 /// <remarks>19 /// Neste aplicativo todos os argumentos de linha de comando20 /// 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ída30 string output = “X coordinate is ” + circle.X + “\n” +31 “Y coordinate is ” + circle.Y + “\n” + 32 “Radius is ” + circle.Radius;33

34 // defi ne as novas coordenadas e o raio35 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 Circle44 output += “Diameter is ” + 45 String.Format( “{0:F}”, circle.Diameter() ) + “\n”;46

47 // exibe a circunferência de Circle48 output += “Circumference is ” +49 String.Format( “{0:F}”, circle.Circumference() ) + “\n”;50

51 // exibe a área de Circle52 output += “Area is ” + 53 String.Format( “{0:F}”, circle.Area() );54

55 MessageBox.Show( output, “Demonstrating Class Circle” );56

57 } // fi m do método Main58


59 } // fi m da classe CircleTest60 }

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 defi nição de classe, antes de uma defi niçã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 fi nalidade) 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 especifi car 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 qualifi cado (por exemplo, System.Console.ReadLine). 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 especifi que 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


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 especifi car. Além disso, pode-se especifi car 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.


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.


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 Confi guration 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.

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

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>Circle</c> inherits from class 11 <c>Point</c>. It has an additional member to12 represent the radius, a property that provides 13 accessto it and method <c>Area</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>Point</c> defi nes a point as a pair21 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>Point</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>Point</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>Point</c>.44 </summary>45 <remarks>46 Sets properties <c>X</c> and <c>Y</c> to 0.47 </remarks>48 </member>49

50 <member name=


51 “M:CircleTest.Point.#ctor(System.Int32,System.Int32)”>52 <summary>53 Constructor for <c>Point</c> 54 that accepts two integers55 that represent the x and y coordinates of the point.56 </summary> 57 <remarks>58 Uses <c>X</c> and <c>Y</c> 59 properties to set the coordinates of the point, 60 not private members <c>x</c> 61 and <c>y</c>.62 </remarks>63 <param name=“xValue”>64 The x coordinate of the circle65 </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>Point</c> to 74 string 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>x</c>.86 </summary>87 <value>88 <c>X</c> accesses the value of the 89 <c>x</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>y</c>.97 </summary>98 <value>99 <c>Y</c> accesses the value of the 100 <c>y</c> data member.101 </value>102 </member>103

104 <member name=“F:CircleTest.Circle.radius”>105 <summary>106 This private member of <c>Circle</c> 107 represents the radius.108 </summary>



109 </member>110

111 <member name=“M:CircleTest.Circle.#ctor”>112 <summary>113 Default constructor for class <c>Circle</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>Circle</c> that accepts two 124 integersthat represent the x and y coordinates of the125 circle and a double that represents the radius.126 </summary>127 <remarks>128 Uses property <c>Radius</c> to set the radius 129 of the circle, not private member 130 <c>radius</c>.131 </remarks>132 <param name=“xValue”>133 The x coordinate of the circle134 </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>Math.PI</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>



167 Computes the area of the circle.168 </summary>169 <remarks>170 Uses constant <c>Math.PI</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>Circle</c> to 181 string format.182 </summary>183 <remarks>184 Overrides <c>ToString</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>radius</c>.197 </summary>198 <remarks>199 The <c>set</c> method 200 ensures that <c>radius</c> 201 is not set to a 202 negative number.203 </remarks>204 <value>205 <c>Radius</c> accesses the value of the 206 <c>radius</c> data member.207 </value>208 </member>209

210 <member name=“T:CircleTest.CircleTest”>211 <summary>212 Class <c>CircleTest</c> inherits from class 213 tests the <c>Point</c> and 214 <c>Point</c> classes.215 </summary>216 </member>217

218 <member name=“M:CircleTest.CircleTest.Main(Sys tem.String[])”>219 <summary>220 Entry point of application.221 </summary>222 <remarks>223 In this application all command-line arguments224 are ignored.



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

231 </members>232 </doc>

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 defi nem 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 é especifi cado 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 fi les 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 qualifi cado. Esse construtor assume dois argumentos int — os parênteses após o nome de cada membro especifi cam o tipo daquele membro.

Resumo

• Os programadores devem documentar as informações específi cas de uma classe, como o papel da classe em um sistema, a funciona-lidade que cada método fornece para a classe e a fi nalidade da variável de cada classe.

• A documentação ajuda todos os programadores a entender como as classes podem interoperar e facilita a modifi caçã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 especifi ca 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 fi nalidade) 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)atributo name do elemento memberBuild Comment Web Pagescódigo-fontecoluna Documentation coluna Members

comentário da documentação XMLconstrutor criando a documentação em XMLdeclaração de métododefi nição de classe defi nição de interface


diretório documentaçãoelemento celemento member elemento paraelemento paramelemento remarkselemento returnselemento seeelemento summary

elemento valuefolha de estilosHTML membro parâmetrospropriedadereferênciatagvalor de retornovariável de instância

Documents

GERANDO DOCUMENTAÇÃO