Documentar tu código con comentarios XMLDocumentar tu código con comentarios XML

  • 01/21/2020
  • 18 minutos de lectura
  • .

    • B
    • o
    • O
  • Los comentarios de documentación XML son un tipo especial de comentario, añadido sobre la definición de un tipo o miembro definido por el usuario.Los comentarios de la documentación XML son un tipo especial de comentario, que se añade sobre la definición de cualquier tipo o miembro definido por el usuario.Son especiales porque pueden ser procesados por el compilador para generar un archivo de documentación XML en tiempo de compilación.El archivo XML generado por el compilador puede ser distribuido con su .NET para que Visual Studio y otros IDEs puedan utilizar IntelliSense para mostrar información rápida sobre tipos o miembros. Además, el archivo XML se puede ejecutar a través de herramientas como DocFX y Sandcastle para generar sitios web de referencia de la API.

    Los comentarios de la documentación XML, al igual que el resto de comentarios, son ignorados por el compilador.

    Puede generar el archivo XML en tiempo de compilación haciendo una de las siguientes cosas:

    • Si desarrolla una aplicación con .NET Core desde la línea de comandos, puede añadir un elemento GenerateDocumentationFile a la sección <PropertyGroup> de su archivo de proyecto. csproj.Si está desarrollando una aplicación con .NET Core desde la línea de comandos, puede añadir un elemento GenerateDocumentationFile a la sección <PropertyGroup> de su archivo de proyecto .csproj. También puede especificar la ruta del archivo de documentación directamente utilizando el elemento DocumentationFile. El siguiente ejemplo genera un archivo XML en el directorio del proyecto con el mismo nombre de archivo raíz que el ensamblaje
      <GenerateDocumentationFile>true</GenerateDocumentationFile>

      Es equivalente a este:

      <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
    • Si está desarrollando una aplicación con Visual Studio, haga clic con el botón derecho del ratón en el proyecto y seleccione Propiedades.Si está desarrollando una aplicación con Visual Studio, haga clic con el botón derecho en el proyecto y seleccione Propiedades. En el diálogo de propiedades, seleccione la pestaña Construir y marque Archivo de documentación XML. También puede cambiar la ubicación en la que el compilador escribe el archivo.

    • Si está compilando un archivo .NET desde la línea de comandos, añada la opción del compilador -doc al compilar.

    • Los comentarios de la documentación XML utilizan tres barras inclinadas (///) y un cuerpo de comentario con formato XML. Por ejemplo:

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

Procedimiento paso a paso

Vayamos a documentar una librería matemática muy básica para facilitar la comprensión/contribución de los nuevos desarrolladores y el uso por parte de terceros.

Aquí tienes el código de la biblioteca matemática simple:Aquí tienes el código de la biblioteca matemática simple:

/* The main Math class Contains all methods for performing basic math functions*/public class Math{ // Adds two integers and returns the result 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 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; } // Subtracts an integer from another and returns the result public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result public static double Divide(double a, double b) { return a / b; }}

La biblioteca de ejemplo soporta cuatro operaciones aritméticas principales ( addsubtractmultiply y divide ) sobre int tipos de datos y.La biblioteca de ejemplo soporta cuatro operaciones aritméticas principales (addsubtractmultiply, y divide) en los tipos de datos int y double.

Ahora quieres ser capaz de crear un documento de referencia de la API a partir de tu código para los desarrolladores de terceros que utilizan tu biblioteca, pero no tienen acceso al código fuente.Ahora quiere ser capaz de crear un documento de referencia de la API a partir de su código para los desarrolladores de terceros que utilizan su biblioteca, pero no tienen acceso al código fuente.Como se mencionó anteriormente etiquetas de documentación XML se puede utilizar para lograr esto. Ahora conocerás las etiquetas XML estándar que soporta el compilador de C#.

<sumario>

La etiqueta <summary> añade información sucinta sobre un tipo o miembro.La etiqueta <summary> añade una breve información sobre un tipo o miembro.Voy a demostrar su uso añadiéndola a la definición de la clase Math y al primer método Add.Demostraré su uso añadiéndolo a la definición de la clase Math y al primer método Add. Siéntete libre de aplicarlo al resto de tu 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; }}

La etiqueta <summary> es importante y te recomendamos que la incluyas ya que su contenido es la fuente principal de información de tipos o miembros en IntelliSense o en un documento de referencia de la API.La etiqueta <summary> es importante, y se recomienda incluirla porque su contenido es la fuente principal de información sobre tipos o miembros en IntelliSense o en un documento de referencia de la API.

<observaciones>

La etiqueta <remarks> complementa la información del tipo o del miembro proporcionada por la etiqueta <summary>.La etiqueta <remarks> complementa la información sobre tipos o miembros que proporciona la etiqueta <summary>. En este ejemplo, sólo lo añadirás a la clase.

/* 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{}

<retornos>

La etiqueta <returns> describe el valor de retorno de una declaración de método.La etiqueta <returns> describe el valor de retorno de una declaración de método.Como antes, el siguiente ejemplo ilustra la etiqueta <returns> en el primer método Add.Como antes, el siguiente ejemplo ilustra la etiqueta <returns> en el primer método Add. Puedes hacer lo mismo con otros 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;}

<valor>

La etiqueta <value> es similar a la etiqueta <returns>, excepto que lo usas para las propiedades.La etiqueta <value> es similar a la etiqueta <returns>, salvo que se utiliza para las propiedades.Suponiendo que tu biblioteca Math tiene una propiedad estática llamada PI, así es como usarías esta etiqueta:Suponiendo que tu biblioteca Math tiene una propiedad estática llamada PI, así es como usarías esta etiqueta:

/* 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; }}

<ejemplo>

La etiqueta <example> te permite incluir un ejemplo de tu documentación XML.Utiliza la etiqueta <example> para incluir un ejemplo en su documentación XML.Esto implica utilizar la etiqueta hija <code>.Se trata de utilizar la etiqueta hija <code>.

// 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;}

La etiqueta code conserva los saltos de línea y la sangría para los ejemplos más largos.La etiqueta code conserva los saltos de línea y la sangría para los ejemplos más largos.

<para>

La etiqueta <para> da formato al contenido dentro de su etiqueta padre.Se utiliza la etiqueta <para> para dar formato al contenido dentro de su etiqueta padre. <para> suele utilizarse en una etiqueta, como <remarks> o <returns>, para dividir el texto en párrafos.<para> suele utilizarse dentro de una etiqueta, como <remarks> o <returns>, para dividir el texto en párrafos.Puede formatear el contenido de la etiqueta <remarks> para su definición de clase.

/* 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>

Siguiendo con el tema del formato, se utiliza la etiqueta <c> para marcar parte del texto como código.Siguiendo con el tema del formato, se utiliza la etiqueta <c> para marcar parte del texto como código.Es como la etiqueta <code> pero en línea. Es útil cuando se quiere mostrar un ejemplo de código rápido como parte del contenido de una etiqueta.Vamos a actualizar la documentación de la clase Math.Vamos a actualizar la documentación de la clase 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{}

<exception>

Al utilizar la etiqueta <exception>, estás informando a tus desarrolladores de que un método puede lanzar excepciones específicas.Al utilizar la etiqueta <exception>, permites que tus desarrolladores sepan que un método puede lanzar excepciones específicas.Si miras tu biblioteca Math, puedes ver que ambos métodos Add lanzan una excepción si se cumple una determinada condición.Mirando su librería Math, se puede ver que ambos métodos Add lanzan una excepción si se cumple una determinada condición. Es menos obvio, sin embargo, que el método Divide utilizado con un entero también lanza una excepción si el parámetro b es cero.No es tan obvio, sin embargo, que el método Divide entero lanza también si el parámetro b es cero. Ahora añade la documentación de la excepción 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; }}

El atributo cref hace referencia a una excepción que está disponible en el entorno de construcción actual.El atributo cref representa una referencia a una excepción que está disponible en el entorno de compilación actual.Puede ser cualquier tipo definido en el proyecto o un ensamblaje referenciado. El compilador emitirá una advertencia si su valor no puede ser resuelto.

<ver>

La etiqueta <see> permite crear un enlace interactivo a una página de documentación de otro fragmento de código.La etiqueta <see> permite crear un enlace clicable a una página de documentación de otro elemento de código. En nuestro siguiente ejemplo, crearemos un enlace clicable entre los dos 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 es un atributo requerido que representa una referencia a un tipo o a sus miembros que está disponible en el entorno de compilación actual.Puede ser cualquier tipo definido en el proyecto o un conjunto referenciado.

<seealso>

Puedes utilizar la etiqueta <seealso> de la misma manera que la etiqueta <see>.Se utiliza la etiqueta <seealso> de la misma manera que la etiqueta <see>. La única diferencia es que su contenido suele colocarse en una sección «Véase también». Aquí añadiremos una etiqueta seealso bajo el método Add utilizado con un entero para referenciar otros métodos de la clase que aceptan parámetros enteros :Aquí añadiremos una etiqueta seealso en el método integer Add para hacer referencia a otros métodos de la clase que aceptan parámetros integer:

/* 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; }}

El atributo cref representa una referencia a un tipo o a sus miembros y está disponible desde el entorno de construcción actual.El atributo cref representa una referencia a un tipo o a su miembro que está disponible en el entorno de compilación actual.Puede ser cualquier tipo definido en el proyecto o un ensamblaje referenciado.

<param>

La etiqueta <param> se utiliza para describir los parámetros de un método.Se utiliza la etiqueta <param> para describir los parámetros de un método. He aquí un ejemplo sobre el método doble Add: El parámetro que describe la etiqueta se especifica en el atributo Required 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>

Se utiliza la etiqueta <typeparam> exactamente igual que la etiqueta <param>, sino para permitir que las declaraciones de tipos o métodos genéricos describan un parámetro genérico.Se utiliza la etiqueta <typeparam> igual que la etiqueta <param> pero para las declaraciones de tipos o métodos genéricos para describir un parámetro genérico.Añade un método genérico rápido a tu clase Math para comprobar si una cantidad es mayor que otra.

/* 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>

Mientras describes lo que hace un método en lo que podría ser una etiqueta <summary>, podrías querer crear una referencia a un parámetro.A veces puedes estar en medio de la descripción de lo que hace un método en lo que podría ser una etiqueta <summary>, y podrías querer hacer una referencia a un parámetro. La etiqueta <paramref> es ideal para esta tarea.La etiqueta <paramref> es ideal para esto. Actualicemos el resumen de nuestro método Add basado en el doble. Al igual que la etiqueta <param>, el nombre del parámetro se especifica en el atributo Required name.Al igual que la etiqueta <param>, el nombre del parámetro se especifica en el atributo Required 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>

Se utiliza la etiqueta <typeparamref> igual que la etiqueta <paramref>, sino para permitir que las declaraciones de tipos o métodos genéricos describan un parámetro genérico.Se utiliza la etiqueta <typeparamref> igual que la etiqueta <paramref> pero para las declaraciones de tipo o método genérico para describir un parámetro genérico.Se puede utilizar el mismo método genérico que se creó 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>

Se utiliza la etiqueta <list> para formatear la información de la documentación como una lista ordenada, una lista no ordenada, o una tabla.La etiqueta <list> se utiliza para dar formato a la información de la documentación en forma de lista ordenada, lista sin ordenar o tabla. Crea una lista no ordenada de todas las operaciones matemáticas que soporta tu biblioteca Math.Haz una lista no ordenada de cada operación matemática que soporta tu biblioteca 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./// <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{}

Puedes hacer una lista o tabla ordenada sustituyendo el atributo type por number o table, respectivamente.Puedes hacer una lista o tabla ordenada cambiando el atributo type por number o table, respectivamente.

<heredardoc>

Puedes utilizar la etiqueta <inheritdoc> para heredar comentarios XML de clases base, interfaces y métodos similares.Puedes utilizar la etiqueta <inheritdoc> para heredar comentarios XML de clases base, interfaces y métodos similares. Esto elimina el copiado y pegado no deseado de comentarios XML duplicados y mantiene automáticamente los comentarios 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{}

AsambleaPonlo todo junto

Si has seguido este tutorial y has aplicado las etiquetas a tu código según sea necesario, tu código debería ser ahora como el siguiente:Si has seguido este tutorial y has aplicado las etiquetas a tu código donde sea necesario, tu código debería tener ahora un aspecto similar al siguiente:

/* 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; }}

A partir de tu código, puedes generar un sitio web de documentación detallado completo con referencias cruzadas interactivas.A partir de su código, puede generar un sitio web de documentación detallado, con referencias cruzadas en las que se puede hacer clic. Pero se enfrenta a otro problema: su código se ha vuelto difícil de leer. Hay tanta información que tamizar que esto va a ser una pesadilla para cualquier desarrollador que quiera contribuir a este código.Por suerte, existe una etiqueta XML que puede ayudarte a solucionar este problema:Por suerte, existe una etiqueta XML que puede ayudarte a solucionar este problema:

<include>

La etiqueta <include> te permite hacer referencia a los comentarios que se encuentran en un archivo XML separado que describe los tipos y miembros de tu código fuente en lugar de colocar los comentarios de documentación directamente en tu archivo de código fuente.La etiqueta <include> le permite referirse a los comentarios en un archivo XML separado que describe los tipos y miembros en su código fuente, en lugar de colocar los comentarios de documentación directamente en su archivo de código fuente.

Ahora vas a mover todas tus etiquetas XML a un archivo XML separado llamado docs.xml.Ahora vas a mover todas tus etiquetas XML a un archivo XML separado llamado docs.xml. Puedes nombrar este archivo como quieras.Siéntete libre de nombrar el archivo como quieras.

<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>

En el XML anterior, los comentarios de la documentación de cada miembro aparecen directamente dentro de una etiqueta con el nombre de lo que hacen. Puedes elegir tu propia estrategia.Ahora que tienes tus comentarios XML en un archivo separado, vamos a ver cómo tu código puede ser más legible usando la etiqueta <include>:Ahora que tienes tus comentarios XML en un archivo separado, veamos cómo tu código puede hacerse más legible usando la etiqueta <include>:

/* 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; }}

Y ahí lo tienes: nuestro código es legible de nuevo, y no se ha perdido ninguna información de la documentación.Y ahí lo tienes: nuestro código vuelve a ser legible, y no se ha perdido ninguna información de la documentación.

El atributo file representa el nombre del archivo XML que contiene la documentación.El atributo file representa el nombre del archivo XML que contiene la documentación.

El atributo path representa una consulta XPath al tag name presente en el file especificado.El atributo path representa una consulta XPath al tag name presente en el file especificado.

El atributo name representa el especificador de nombre en la etiqueta que precede a los comentarios.El atributo name representa el especificador del nombre en la etiqueta que precede a los comentarios.

El atributo id, que puede utilizarse en lugar de name , representa el ID de la etiqueta que precede a los comentarios.El atributo id, que puede utilizarse en lugar de name, representa el ID de la etiqueta que precede a los comentarios.

Etiquetas definidas por el usuarioEtiquetas definidas por el usuario

Todas las etiquetas señaladas anteriormente representan las que reconoce el compilador de C#. Sin embargo, el usuario es libre de definir sus propias etiquetas.Herramientas como Sandcastle aportan soporte para etiquetas adicionales como <event> y <note> , e incluso soportan documentación de espacios de nombres.Herramientas como Sandcastle aportan soporte para etiquetas extra como <event> y <note>, e incluso soportan la documentación de espacios de nombres.También se pueden utilizar herramientas de generación de documentación personalizadas o propias con las etiquetas estándar y se pueden admitir múltiples formatos de salida, desde HTML hasta PDF.

RecomendacionesRecomendaciones

La documentación del código es recomendable por muchas razones. Lo que sigue son algunas de las mejores prácticas, escenarios de casos de uso general, y cosas que usted debe saber cuando se utilizan etiquetas de documentación XML en su código C#.

  • En aras de la coherencia, todos los tipos visibles públicamente y sus miembros deben ser documentados. Si debes hacerlo, hazlo todo.
  • Los miembros privados también pueden documentarse mediante comentarios XML. Sin embargo, esto expone el funcionamiento interno (potencialmente confidencial) de su biblioteca.
  • Como mínimo, los tipos y sus miembros deben tener una etiqueta <summary> porque su contenido es necesario para IntelliSense.
  • El texto de la documentación debe redactarse utilizando oraciones completas que terminen con puntos suspensivos.
  • Las clases parciales son totalmente compatibles, y la información de la documentación se concatenará en una única entrada para ese tipo.
  • El compilador comprueba la sintaxis de <exception><include> tags,,,, <param><see><seealso> y <typeparam> .El compilador verifica la sintaxis del <exception><include><param><see><seealso>, y <typeparam> etiquetas.
  • El compilador valida los parámetros que contienen rutas de archivos y referencias a otras partes del código.

Ver tambiénVer también

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *