Documentar o seu código com comentários XMLDocumentar o seu código com comentários XML

  • 01/21/2020
  • 18 minutos para ler
  • B
  • o
  • O

/li>

comentários de documentação XML são um tipo especial de comentário, adicionado acima a definição de um tipo ou membro definido pelo utilizador.Os comentários da documentação XML são um tipo especial de comentário, adicionado acima da definição de qualquer tipo ou membro definido pelo utilizador.São especiais porque podem ser processados pelo compilador para gerar um ficheiro de documentação XML em tempo de compilação. O ficheiro XML gerado pelo compilador pode ser distribuído com o seu .NET para que o Visual Studio e outras IDEs possam utilizar o IntelliSense para mostrar informação rápida sobre tipos ou membros. Adicionalmente, o ficheiro XML pode ser executado através de ferramentas como DocFX e Sandcastle para gerar sites de referência API.

Os comentários da documentação XML, como todos os outros comentários, são ignorados pelo compilador.

P>Pode gerar o ficheiro XML em tempo de compilação fazendo uma das seguintes opções:

  • Se desenvolver uma aplicação com .NET Core da linha de comando, pode adicionar um GenerateDocumentationFile elemento ao <PropertyGroup> secção do seu ficheiro de projecto. csproj.Se estiver a desenvolver uma aplicação com .NET Core a partir da linha de comando, pode adicionar um elemento GenerateDocumentationFile ao elemento <PropertyGroup> secção do seu ficheiro de projecto .csproj. Pode também especificar o caminho para o ficheiro de documentação directamente usando DocumentationFile elemento. O exemplo seguinte gera um ficheiro XML no directório do projecto com o mesmo nome de ficheiro raiz da assembleia:O exemplo seguinte gera um ficheiro XML no directório do projecto com o mesmo nome de ficheiro raiz da assembleia:

    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    é equivalente a este:

    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  • se estiver a desenvolver uma aplicação utilizando o Visual Studio, clique com o botão direito do rato sobre o projecto, depois seleccione Propriedades.Se estiver a desenvolver uma aplicação utilizando o Visual Studio, clique com o botão direito do rato sobre o projecto e seleccione Propriedades. No diálogo de propriedades, seleccione o separador Construir, e verifique o ficheiro de documentação XML. Também pode alterar o local para onde o compilador escreve o ficheiro.

  • se estiver a compilar um .NET a partir da linha de comando, adicionar a opção -doc compiler ao compilar.

XML documentação comentários usam triplos cortes (///) e um corpo de comentários em formato XML. Por exemplo:

/// <summary>/// This class does something./// </summary>public class SomeClass{}

Procedimento passo-a-passoPassar a pé

Passar a pé pela documentação de uma biblioteca matemática muito básica para facilitar a compreensão/contribuição por parte de novos programadores e a utilização por parte de programadores terceiros.

Código para a biblioteca matemática simples:Aqui está o código para a biblioteca matemática simples:

A biblioteca de exemplos suporta quatro operações aritméticas principais ( addsubtractmultiply e divide ) em int tipos de double dados eA biblioteca de amostras suporta quatro operações aritméticas principais (addsubtractmultiply, e divide) em int e double tipos de dados.

Agora pretende ser capaz de criar um documento de referência API a partir do seu código para programadores terceiros que utilizam a sua biblioteca, mas que não têm acesso ao código fonte.Agora quer ser capaz de criar um documento de referência API a partir do seu código para desenvolvedores terceiros que utilizam a sua biblioteca mas não têm acesso ao código-fonte. Como mencionado anteriormente, as etiquetas de documentação XML podem ser utilizadas para o conseguir. Será agora introduzido às etiquetas XML padrão que o compilador C# suporta.

<summary>

The <summary> tag adiciona informação sucinta sobre um tipo ou membro.O <summary> tag adiciona breve informação sobre um tipo ou membro. Demonstrarei a sua utilização adicionando-a à definição de classe Math e o primeiro método Add.Demonstrarei a sua utilização adicionando-a ao método Math class definition e o primeiro Add. Sinta-se à vontade para o aplicar ao resto do seu código.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>public class Math{ // Adds two integers and returns the result /// <summary> /// Adds two integers and returns the result. /// </summary> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

O <summary> tag é importante e recomendamos que o inclua, uma vez que o seu conteúdo é a principal fonte de informação do tipo ou membro no IntelliSense ou num documento de referência API.O <summary> tag é importante, e recomendamos que o inclua porque o seu conteúdo é a principal fonte de informação do tipo ou membro no IntelliSense ou num documento de referência API.

<remarks>

O <remarks> tag suplementa a informação do tipo ou membro fornecida pelo <summary> tag.O <remarks> tag suplementa a informação sobre tipos ou membros que o <summary> tag fornece. Neste exemplo, basta adicioná-lo à aula.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// This class can add, subtract, multiply and divide./// </remarks>public class Math{}

<returns>

O <returns> tag fornece uma descrição do valor de retorno de uma declaração de método.O <returns> tag descreve o valor de retorno de uma declaração de método. Como antes, o exemplo seguinte ilustra o <returns> tag no primeiro método Add.Como antes, o exemplo seguinte ilustra o método <returns> tag no primeiro Add. O mesmo se pode fazer com outros métodos.

// Adds two integers and returns the result/// <summary>/// Adds two integers and returns the result./// </summary>/// <returns>/// The sum of two integers./// </returns>public static int Add(int a, int b){ // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b;}

<value>

The <value> tag é semelhante ao <returns> tag, excepto que a utiliza para propriedades.O <value> tag é semelhante ao <returns> tag, excepto que o utilize para propriedades.Assumindo que o seu Math biblioteca tem uma propriedade estática chamada PI, eis como utilizaria esta tag:Assumindo que o seu Math biblioteca tem uma propriedade estática chamada PI, eis como utilizaria esta tag:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// This class can add, subtract, multiply and divide./// These operations can be performed on both integers and doubles/// </remarks>public class Math{ /// <value>Gets the value of PI.</value> public static double PI { get; }}

<example>

The <example> tag permite-lhe incluir um exemplo da sua documentação XML.Utiliza a tag <example> para incluir um exemplo na sua documentação XML, o que implica utilizar a tag criança <code>.Isto envolve a utilização da criança <code> tag.

// Adds two integers and returns the result/// <summary>/// Adds two integers and returns the result./// </summary>/// <returns>/// The sum of two integers./// </returns>/// <example>/// <code>/// int c = Math.Add(4, 5);/// if (c > 10)/// {/// Console.WriteLine(c);/// }/// </code>/// </example>public static int Add(int a, int b){ // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b;}

The tag retém as quebras de linha e a indentação para exemplos mais longos.O code tag preserva quebras de linha e indentação para exemplos mais longos.

<para>

O <para> tag formata o conteúdo dentro da sua tag pai. Utiliza-se a tag <para> tag para formatar o conteúdo dentro da sua tag pai. <para> é normalmente usado numa etiqueta, tal como <remarks> ou <returns>, para dividir o texto em parágrafos.<para> é normalmente usado dentro de uma etiqueta, tal como <remarks> ou <returns>, para dividir o texto em parágrafos.Pode formatar o conteúdo da tag <remarks> para a definição da sua classe.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// <para>This class can add, subtract, multiply and divide.</para>/// <para>These operations can be performed on both integers and doubles.</para>/// </remarks>public class Math{}

<c>

Ainda sobre o tema da formatação, usa-se a tag <c> para marcar parte do texto como código.Ainda sobre o tema da formatação, usa-se o <c> tag para marcar parte do texto como código. É como o <code> tag mas em linha. É útil quando se quer mostrar um exemplo de código rápido como parte do conteúdo de uma tag. Vamos actualizar a documentação para a classe Math.Vamos actualizar a documentação para a classe Math.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{}

<excepção>

Ao utilizar a tag <exception>, está a informar os seus programadores de que um método pode levantar excepções específicas.Ao usar o <exception> tag, avisa os seus programadores que um método pode lançar excepções específicas. Se olhar para o seu Math biblioteca, pode ver que ambos os métodos Add lançam uma excepção se uma determinada condição for satisfeita.Olhando para o seu Math biblioteca, pode ver que ambos Add métodos lançam uma excepção se uma determinada condição for satisfeita. É menos óbvio, porém, que o Divide método utilizado com um número inteiro também lança uma excepção se o parâmetro b for zero. Agora adicionar documentação de excepção a este método.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Divides an integer by another and returns the result. /// </summary> /// <returns> /// The division of two integers. /// </returns> /// <exception cref="System.DivideByZeroException">Thrown when a division by zero occurs.</exception> public static int Divide(int a, int b) { return a / b; } /// <summary> /// Divides a double by another and returns the result. /// </summary> /// <returns> /// The division of two doubles. /// </returns> /// <exception cref="System.DivideByZeroException">Thrown when a division by zero occurs.</exception> public static double Divide(double a, double b) { return a / b; }}

The cref attribute references an exception that is available from the current build environment.O atributo cref representa uma referência a uma excepção que está disponível a partir do ambiente de compilação actual, podendo ser qualquer tipo definido no projecto ou uma montagem referenciada. O compilador emitirá um aviso se o seu valor não puder ser resolvido.

< ver>

O <see> tag permite-lhe criar uma ligação interactiva a uma página de documentação para outra peça de código.A tag <see> permite-lhe criar um link clicável para uma página de documentação para outro elemento de código. No nosso próximo exemplo, vamos criar uma ligação clicável entre os dois métodos Add.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

cref é um atributo obrigatório que representa uma referência a um tipo ou aos seus membros que está disponível a partir do ambiente de compilação actual.Este pode ser qualquer tipo definido no projecto ou uma montagem referenciada.

<seealso>

P>Pode usar o <seealso> tag da mesma forma que o <see> tag.Utiliza-se o <seealso> tag da mesma forma que se faz o <see> tag. A única diferença é que o seu conteúdo é tipicamente colocado numa secção “Ver Também”. Aqui vamos adicionar um seealso tag sob o Add método utilizado com um número inteiro para referenciar outros métodos na classe que aceitam parâmetros de número inteiro :Aqui vamos adicionar um seealso tag no inteiro Add método para referenciar outros métodos na classe que aceitam parâmetros inteiros:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

O atributo cref representa uma referência a um tipo ou aos seus membros e está disponível a partir do ambiente de construção actual.O atributo cref representa uma referência a um tipo ou ao seu membro que está disponível a partir do ambiente de compilação actual, podendo ser qualquer tipo definido no projecto ou uma montagem referenciada.

<param>

O <param> tag é usado para descrever os parâmetros de um método. Eis um exemplo no duplo Add método: O parâmetro que a etiqueta descreve é especificado no atributo requerido name.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

<typeparam>

Usa-se o <typeparam> tag exactamente como o <param> tag, mas para permitir declarações genéricas de tipo ou método para descrever um parâmetro genérico.Utiliza-se <typeparam> tag tal como o <param> tag mas para declarações genéricas de tipo ou método para descrever um parâmetro genérico.Adicione um método genérico rápido ao seu Math classe para verificar se uma quantidade é maior do que outra.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Checks if an IComparable is greater than another. /// </summary> /// <typeparam name="T">A type that inherits from the IComparable interface.</typeparam> public static bool GreaterThan<T>(T a, T b) where T : IComparable { return a.CompareTo(b) > 0; }}

<paramref>

Enquanto descreve o que um método faz no que pode ser um <summary> tag, pode querer criar uma referência a um parâmetro.Por vezes pode estar no meio da descrição do que um método faz no que poderia ser um <summary> tag, e pode querer fazer uma referência a um parâmetro. O <paramref> tag é óptimo apenas para esta tarefa. O <paramref> tag é óptimo apenas para esta tarefa. Vamos actualizar o resumo do nosso método de dupla base Add. Vamos actualizar o resumo do nosso método de dupla base Add. Tal como o <param> tag, o nome do parâmetro é especificado no atributo requerido name. Tal como o <param> tag, o nome do parâmetro é especificado no atributo requerido name.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

<typeparamref>

Usa-se o <typeparamref> tag tal como o <paramref> tag, mas para permitir declarações genéricas de tipo ou método para descrever um parâmetro genérico.Utiliza <typeparamref> tag tal como o <paramref> tag mas para declarações genéricas de tipo ou método para descrever um parâmetro genérico, pode utilizar o mesmo método genérico que criou anteriormente.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Checks if an IComparable <typeparamref name="T"/> is greater than another. /// </summary> /// <typeparam name="T">A type that inherits from the IComparable interface.</typeparam> public static bool GreaterThan<T>(T a, T b) where T : IComparable { return a.CompareTo(b) > 0; }}

<list>

Usa-se o <list> tag para formatar a informação da documentação como uma lista ordenada, uma lista não classificada, ou uma tabela.Utiliza-se o <list> tag para formatar informação de documentação como lista ordenada, lista não ordenada, ou tabela. Crie uma lista não ordenada de todas as operações matemáticas suportadas pelo seu Math biblioteca. Faça uma lista não ordenada de todas as operações matemáticas o seu Math biblioteca suporta.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// <list type="bullet">/// <item>/// <term>Add</term>/// <description>Addition Operation</description>/// </item>/// <item>/// <term>Subtract</term>/// <description>Subtraction Operation</description>/// </item>/// <item>/// <term>Multiply</term>/// <description>Multiplication Operation</description>/// </item>/// <item>/// <term>Divide</term>/// <description>Division Operation</description>/// </item>/// </list>/// </summary>public class Math{}

Pode fazer uma lista ou tabela ordenada substituindo o atributo type por number ou table, respectivamente.Pode fazer uma lista ou tabela ordenada alterando o type atributo a number ou table, respectivamente.

<inheritdoc>

P>Pode usar a tag <inheritdoc> para herdar comentários XML de classes base, interfaces e métodos semelhantes.Pode usar a tag <inheritdoc> para herdar comentários XML de classes base, interfaces, e métodos semelhantes. Isto elimina a cópia e colagem indesejada de comentários XML duplicados e mantém automaticamente os comentários XML sincronizados.

/* The IMath interface The main Math class Contains all methods for performing basic math functions*//// <summary>/// This is the IMath interface./// </summary>public interface IMath{}/// <inheritdoc/>public class Math : IMath{}

AssemblagePut it all together

Se seguiu este tutorial e aplicou as etiquetas ao seu código conforme necessário, o seu código deve agora ser parecido com o seguinteSe seguiu este tutorial e aplicou as etiquetas ao seu código quando necessário, o seu código deve agora ser semelhante ao seguinte:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// <list type="bullet">/// <item>/// <term>Add</term>/// <description>Addition Operation</description>/// </item>/// <item>/// <term>Subtract</term>/// <description>Subtraction Operation</description>/// </item>/// <item>/// <term>Multiply</term>/// <description>Multiplication Operation</description>/// </item>/// <item>/// <term>Divide</term>/// <description>Division Operation</description>/// </item>/// </list>/// </summary>/// <remarks>/// <para>This class can add, subtract, multiply and divide.</para>/// <para>These operations can be performed on both integers and doubles.</para>/// </remarks>public class Math{ // Adds two integers and returns the result /// <summary> /// Adds two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Adds two doubles and returns the result /// <summary> /// Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Add(4.5, 5.4); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Subtracts an integer from another and returns the result /// <summary> /// Subtracts <paramref name="b"/> from <paramref name="a"/> and returns the result. /// </summary> /// <returns> /// The difference between two integers. /// </returns> /// <example> /// <code> /// int c = Math.Subtract(4, 5); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Subtract(double, double)"/> to subtract doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result /// <summary> /// Subtracts a double <paramref name="b"/> from another double <paramref name="a"/> and returns the result. /// </summary> /// <returns> /// The difference between two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Subtract(4.5, 5.4); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Subtract(int, int)"/> to subtract integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result /// <summary> /// Multiplies two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The product of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Multiply(4, 5); /// if (c > 100) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Multiply(double, double)"/> to multiply doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result /// <summary> /// Multiplies two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The product of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Multiply(4.5, 5.4); /// if (c > 100.0) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Multiply(int, int)"/> to multiply integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result /// <summary> /// Divides an integer <paramref name="a"/> by another integer <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The quotient of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Divide(4, 5); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> /// See <see cref="Math.Divide(double, double)"/> to divide doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <param name="a">An integer dividend.</param> /// <param name="b">An integer divisor.</param> public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result /// <summary> /// Divides a double <paramref name="a"/> by another double <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The quotient of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Divide(4.5, 5.4); /// if (c > 1.0) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> /// See <see cref="Math.Divide(int, int)"/> to divide integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <param name="a">A double precision dividend.</param> /// <param name="b">A double precision divisor.</param> public static double Divide(double a, double b) { return a / b; }}

Do seu código, pode gerar um website de documentação detalhada, completo com referências cruzadas interactivas.A partir do seu código, pode gerar uma página de documentação detalhada completa com referências cruzadas clicáveis. Mas está confrontado com outro problema: o seu código tornou-se difícil de ler. Há tanta informação para analisar que isto vai ser um pesadelo para qualquer programador que queira contribuir para este código.Felizmente, existe uma tag XML que o pode ajudar a lidar com este problema:Felizmente, existe uma tag XML que o pode ajudar a lidar com isto:

<include>

The <include> tag permite-lhe referenciar comentários encontrados num ficheiro XML separado descrevendo os tipos e membros do seu código fonte em vez de colocar comentários de documentação directamente no seu ficheiro de código fonte.A tag <include> permite-lhe consultar os comentários num ficheiro XML separado que descreve os tipos e membros no seu código-fonte, por oposição a colocar comentários de documentação directamente no seu ficheiro de código-fonte.

Agora vai mover todas as suas etiquetas XML para um ficheiro XML separado chamado docs.xml.Agora vai mover todas as suas etiquetas XML para um ficheiro XML separado chamado docs.xml. Pode dar o nome que quiser a este ficheiro. Sinta-se à vontade para dar o nome que quiser.

<docs> <members name="math"> <Math> <summary> The main <c>Math</c> class. Contains all methods for performing basic math functions. </summary> <remarks> <para>This class can add, subtract, multiply and divide.</para> <para>These operations can be performed on both integers and doubles.</para> </remarks> </Math> <AddInt> <summary> Adds two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The sum of two integers. </returns> <example> <code> int c = Math.Add(4, 5); if (c > 10) { Console.WriteLine(c); } </code> </example> <exception cref="System.OverflowException">Thrown when one parameter is max and the other is greater than 0.</exception> See <see cref="Math.Add(double, double)"/> to add doubles. <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </AddInt> <AddDouble> <summary> Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The sum of two doubles. </returns> <example> <code> double c = Math.Add(4.5, 5.4); if (c > 10) { Console.WriteLine(c); } </code> </example> <exception cref="System.OverflowException">Thrown when one parameter is max and the other is greater than 0.</exception> See <see cref="Math.Add(int, int)"/> to add integers. <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </AddDouble> <SubtractInt> <summary> Subtracts <paramref name="b"/> from <paramref name="a"/> and returns the result. </summary> <returns> The difference between two integers. </returns> <example> <code> int c = Math.Subtract(4, 5); if (c > 1) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Subtract(double, double)"/> to subtract doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </SubtractInt> <SubtractDouble> <summary> Subtracts a double <paramref name="b"/> from another double <paramref name="a"/> and returns the result. </summary> <returns> The difference between two doubles. </returns> <example> <code> double c = Math.Subtract(4.5, 5.4); if (c > 1) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Subtract(int, int)"/> to subtract integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </SubtractDouble> <MultiplyInt> <summary> Multiplies two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The product of two integers. </returns> <example> <code> int c = Math.Multiply(4, 5); if (c > 100) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Multiply(double, double)"/> to multiply doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </MultiplyInt> <MultiplyDouble> <summary> Multiplies two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The product of two doubles. </returns> <example> <code> double c = Math.Multiply(4.5, 5.4); if (c > 100.0) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Multiply(int, int)"/> to multiply integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </MultiplyDouble> <DivideInt> <summary> Divides an integer <paramref name="a"/> by another integer <paramref name="b"/> and returns the result. </summary> <returns> The quotient of two integers. </returns> <example> <code> int c = Math.Divide(4, 5); if (c > 1) { Console.WriteLine(c); } </code> </example> <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> See <see cref="Math.Divide(double, double)"/> to divide doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <param name="a">An integer dividend.</param> <param name="b">An integer divisor.</param> </DivideInt> <DivideDouble> <summary> Divides a double <paramref name="a"/> by another double <paramref name="b"/> and returns the result. </summary> <returns> The quotient of two doubles. </returns> <example> <code> double c = Math.Divide(4.5, 5.4); if (c > 1.0) { Console.WriteLine(c); } </code> </example> <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> See <see cref="Math.Divide(int, int)"/> to divide integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <param name="a">A double precision dividend.</param> <param name="b">A double precision divisor.</param> </DivideDouble> </members></docs>

No XML acima, os comentários da documentação de cada membro aparecem directamente dentro de uma etiqueta com o nome do que faz. Pode escolher a sua própria estratégia.Agora que tem os seus comentários XML num ficheiro separado, vamos ver como o seu código pode ser tornado mais legível usando a tag <include>:Agora que tem os seus comentários XML num ficheiro separado, vamos ver como o seu código pode ser tornado mais legível usando o <include> tag:

/* The main Math class Contains all methods for performing basic math functions*//// <include file='docs.xml' path='docs/members/Math/*'/>public class Math{ // Adds two integers and returns the result /// <include file='docs.xml' path='docs/members/AddInt/*'/> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Adds two doubles and returns the result /// <include file='docs.xml' path='docs/members/AddDouble/*'/> public static double Add(double a, double b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Subtracts an integer from another and returns the result /// <include file='docs.xml' path='docs/members/SubtractInt/*'/> public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result /// <include file='docs.xml' path='docs/members/SubtractDouble/*'/> public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result /// <include file='docs.xml' path='docs/members/MultiplyInt/*'/> public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result /// <include file='docs.xml' path='docs/members/MultiplyDouble/*'/> public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result /// <include file='docs.xml' path='docs/members/DivideInt/*'/> public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result /// <include file='docs.xml' path='docs/members/DivideDouble/*'/> public static double Divide(double a, double b) { return a / b; }}

E aí tem: o nosso código é novamente legível, e nenhuma informação de documentação foi perdida.E aí está: o nosso código voltou a ser legível, e nenhuma informação de documentação foi perdida.

O atributo file representa o nome do ficheiro XML que contém a documentação.O atributo file representa o nome do ficheiro XML contendo a documentação.

O atributo path representa uma consulta XPath para o atributo tag name presente no file especificado.O atributo path representa uma consulta XPath para o atributo tag name presente no file.

p> O atributonamerepresenta o especificador do nome na etiqueta que precede os comentários.O atributonamerepresenta o especificador do nome na etiqueta que precede os comentários.

O atributo id , que pode ser utilizado no lugar de name , representa o identificador da etiqueta que precede os comentários.O atributo id, que pode ser utilizado no lugar de name, representa o ID da etiqueta que precede os comentários.

Tags definidas pelo utilizador Tags definidas pelo utilizador

Todas as tags delineadas acima representam as que são reconhecidas pelo compilador C#. No entanto, um utilizador é livre de definir as suas próprias etiquetas.Ferramentas como Sandcastle trazem suporte para etiquetas adicionais como <event> e < nota> , e até suporta documentação do namespace.Ferramentas como Sandcastle trazem suporte para etiquetas extra como <event> e < nota>, e até suportam a documentação de namespaces.Ferramentas de geração de documentação personalizadas ou internas também podem ser utilizadas com as etiquetas padrão e podem ser suportados múltiplos formatos de saída de HTML para PDF.

RecomendaçõesRecomendações

Código de documentação é recomendado por muitas razões. O que se segue são algumas melhores práticas, cenários de casos de uso geral, e coisas que deve saber quando utilizar etiquetas de documentação XML no seu código C#.

  • Por uma questão de consistência, todos os tipos visíveis publicamente e os seus membros devem ser documentados. Se tiver de o fazer, faça-o todo.
  • Membros privados também podem ser documentados usando comentários XML. No entanto, isto expõe o funcionamento interno (potencialmente confidencial) da sua biblioteca.
  • No mínimo, os tipos e os seus membros devem ter uma etiqueta <summary> porque o seu conteúdo é necessário para o IntelliSense.
  • O texto da documentação deve ser escrito usando frases completas terminando com paragens completas.
  • Classes parciais são totalmente suportadas, e a informação da documentação será concatenada numa única entrada para esse tipo.
  • O compilador verifica a sintaxe de <exception><include> tags,,,,, <param><see><seealso> e <typeparam> .O compilador verifica a sintaxe do <exception><include><param><see><seealso>, e <typeparam> tags.
  • O compilador valida os parâmetros que contêm os caminhos dos ficheiros e referências a outras partes do código.

Ver tambémSee também

Deixe uma resposta

O seu endereço de email não será publicado. Campos obrigatórios marcados com *