Comentarios de documentación XML

En C# puedes crear documentación para tu código a tráves del uso de elementos XML en el especial tags de comentarios (defindidos dentro triple slashes ///) en el código fuente antes del bloque de código al que se refiere el comentario. por ejemplo:

/// <summary>
/// Fecha de ingreso del empleado.
/// </summary>
public DateTime FechaDeIngreso { get; set; }

Cuando compilas tu código con la opción /doc, el compilador buscará todas las etiquetas XML en el código fuente y crea un archivo XML de documentación. Para crear la documentación final basada del archivo XML de documentación, puedes crear una herramienta personalizada o usar una herramienta para la generación de documentación como SandCastle.

Los comentarios de documentación XML no son metadata; estos no son incluidos en el ensamblador y por tal motivo no pueden ser accedidos por reflection.

Etiquetas recomendadas para los comentarios de documentación XML

Las etiquetas se procesan en construcciones de código, como tipos (types) y tipos de miembros (types member).

Nota: Los comentarios de documentación no pueden ser aplicados a un namespace.

El compilador procesará cualquier etiqueta XML que sea válida. Las siguientes etiquetas proporcionan funcionalidad generalmente utilizada en la documentación del código.

Etiquetas

<c>	<para>	<see>*	<code>
<param>*	<seealso>*	<example>	<paramref>
<summary>	<exception>*	<permission>*	<typeparam>*
<include>*	<remarks>	<typeparamref>	<list>
<returns>	<value>

(*: el compilador verifica la sintaxis.)

<c>

Sintaxis

<c>text</c>

Parametros

text: El texto que deseas indicar como código.

Observaciones

La etiqueta <c> da una manera de indicar que el texto dentro de una descripción debe estar marcado como código.

Usar <code> para indicar multiples líneas de código.

Ejemplo

/// Texto para la clase ClasePrueba.
public class ClasePrueba
{
    /// <summary>
    /// <c>HacerTrabajo</c> es un método de la clase <c>ClasePrueba</c>.
    /// </summary>
    public static void HacerTrabajo(int Int1)
    {
    }

    /// Comentario para Main.
    static void Main()
    {
    }
}

<para>

Sintaxis

<para>content</para>

Parametros

content: El texto del parrafo.

Observaciones

La etiqueta <para> es una etiqueta contenida que puede ser usada dentro de <summary>, <remarks>, o <returns>, y permite darle estructura al texto.

Ejemplo

/// Texto para la clase ClasePrueba.
public class ClasePrueba
{
    /// <summary>HacerTrabajo es un método de la clase ClasePrueba.
    /// <para>Aquí podemos definir un segundo parrafo de una descrpción.</para>
    /// </summary>
    public static void HacerTrabajo(int Int1)
    {
    }
}

<see>

Sintaxis

<see cref="member"/>

Parametros

cref="member": Una referencia de un miembro o campo que es habilitado para ser llamado desde el ambiente de compilación actual. El compilador verifica que el elemento existe en el código y pasa el miembro al nombre del elemento en el XML de salida. Escribir el miembro dentro de comillas dobles (" ").

Observaciones

La etiqueta <see> te permite especificar un enlace (link) dentro del texto. Usa <seealso> para indicar que el texto debe ser ubicado en la sección Ver También (See Also). Usa el atributo cref para crear hyperlinks internos en las páginas de la documentación para los elementos de código.

Ejemplo

/// Texto para la clase ClasePrueba.
public class ClasePrueba
{
    /// <summary>HacerTrabajo es un método de la clase ClasePrueba.
    /// <para>Aquí podemos definir un segundo parrafo de una descrpción. <see cref="System.Console.WriteLine\(System.String\)"/> para información acerca de sentencias de salidas.</para>
    /// </summary>
    public static void DoWork(int Int1)
    {
    }
}

<code>

Sintaxis

<code>content</code>

Parametros

content: El texto que quieres marcar como código.

Observaciones

La etiqueta <code> te da una manera de definir multiples líneas de texto como de código. Usa <c> para indicar que el texto de una descripción debe estar marcado como código.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class ClasePrueba
{
    /// <summary>
    /// Este ejemplo muestra como especificar el cosntructor de <see cref="ClasePrueba"/> como un atributo cref.
    /// </summary>
    public ClasePrueba()
    {
    }

    /// <summary>
    /// Este ejemplo muestra como especificar el cosntructor de <see cref="ClasePrueba(int)"/> como un atributo cref.
    /// </summary>
    public ClasePrueba(int value)
    {
    }

    /// <summary>
    /// El métoddo GetZero.
    /// </summary>
    /// <example> 
    /// Este ejemplo muestra como llamar el método <see cref="GetZero"/>.
    /// <code>
    /// class ClasePrueba 
    /// {
    ///     static int Main() 
    ///     {
    ///         return GetZero();
    ///     }
    /// }
    /// </code>
    /// </example>
    public static int GetZero()
    {
        return 0;
    }
}

<param>

Sintaxis

<param name="name">description</param>

Parametros

name: El nombre de un parametro del método. Escribir el nombre dentro de comillas dobles (" ").

description: Una descripción para el parametro.

Observaciones

La etiqueta <param> debe ser usada en el comentario de la definición un método para describir uno de los parametros del método. Para cada parametro se debe definir una etiqueta <param>.

El texto para la etiqueta <param> se mostrará en IntelliSense, el Object Browser, y en el reporte Code Comment Web.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class ClasePrueba
{
    /// Parametro único.
    /// <param name="Int1">Usado para indicar estado.</param>
    public static void DoWork(int Int1)
    {
    }

    // Multiples parametros.
    /// <param name="Int1">Usado para indicar estado.</param>
    /// <param name="Float1">Usado para especificar contexto.</param>
    public static void DoWork(int Int1, float Float1)
    {
    }
}

<seealso>

Sintaxis

<seealso cref="member"/>

Parametros

Observaciones

La etiqueta <seealso> te permite especificar el texto que desear que aparezca en la sección Ver También (See Also). Usa <see> para especificar un link para el texto contenido.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class TestClass
{
    /// <summary>HacerTrabajo es un método de la clase HacerTrabajo.
    /// <para>Aquí podemos definir un segundo parrafo de una descrpción. <see cref="System.Console.WriteLine(System.String)"/> para información acerca de sentencias de salidas.</para>
    /// <seealso cref="TestClass.Main"/>
    /// </summary>
    public static void HacerTrabajo(int Int1)
    {
    }

    /// Texto para Main
    static void Main()
    {
    }
}

<example>

Sintaxis

<example>description</example>

Parametros

description: Una descripción del ejemplo de código.

Observaciones

La etiqueta <example> le permite especificar un ejemplo de cómo usar un método u otro miembro de biblioteca. Esto normalmente implica el uso de la etiqueta <code>.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class ClasePrueba
{
    /// <summary>
    /// Este ejemplo muestra como especificar el cosntructor de <see cref="ClasePrueba"/> como un atributo cref.
    /// </summary>
    public ClasePrueba()
    {
    }

    /// <summary>
    /// Este ejemplo muestra como especificar el cosntructor de <see cref="ClasePrueba(int)"/> como un atributo cref.
    /// </summary>
    public ClasePrueba(int value)
    {
    }

    /// <summary>
    /// El métoddo GetZero.
    /// </summary>
    /// <example> 
    /// Este ejemplo muestra como llamar el método <see cref="GetZero"/>.
    /// <code>
    /// class ClasePrueba 
    /// {
    ///     static int Main() 
    ///     {
    ///         return GetZero();
    ///     }
    /// }
    /// </code>
    /// </example>
    public static int GetZero()
    {
        return 0;
    }
}

<paramref>

Sintaxis

<paramref name="name"/>

Parametros

name: Nombre del parámetro al que se hace referencia. Ponga el nombre entre comillas dobles (" ").

Observaciones

La etiqueta <paramref> ofrece una manera de indicar que una palabra en los comentarios del código (por ejemplo, en un bloque <summary> o <comments>) hace referencia a un parámetro. El archivo XML se puede procesar para dar formato a esta palabra de alguna manera distinta, por ejemplo, con una fuente en negrita o cursiva.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class ClasePrueba
{
    /// <summary>DoWork es un método de la clase ClasePrueba.  
    /// El parametro <paramref name="Int1"/> recibe un número entero.
    /// </summary>
    public static void DoWork(int Int1)
    {
    }
}

<summary>

Sintaxis

<summary>description</summary>

Parametros

description: Resumen del objeto.

Observaciones

La etiqueta <summary> debe usarse para describir un tipo o un miembro de tipo. Usa <remarks> para agregar información adicional a una descripción de tipo. Usa el atributo cref para permitir que herramientas de documentación como Sandcastle creen hipervínculos internos a las páginas de documentación de los elementos de código.

El texto de la etiqueta <summary> es la única fuente de información sobre el tipo en IntelliSense y también se muestra en la ventana Objects Browser.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
public class ClasePrueba
{
    /// <summary>DoWork es un método de la clase ClasePrueba.  
    /// <para>Aqui puedes hacer un segundo parrafo en la descripción.</para>
    /// </summary>
    public static void DoWork(int Int1)
    {
    }
}

<exception>

Sintaxis

<exception cref="member">description</exception>

Parametros

cref="member": Una referencia a una excepción que está disponible desde el entorno de compilación actual. El compilador comprueba si la excepción dada existe y traduce member al nombre de elemento canónico en la salida XML. member debe aparecer entre comillas dobles (" ").

description: Descripción de la excepción.

Observaciones

La etiqueta <exception> te permite especificar qué excepciones se pueden producir. Esta etiqueta se puede aplicar a definiciones de métodos, propiedades, eventos e indexaciones.

Ejemplo

/// Comentario para la clase.
public class EClass : System.Exception
{
    // Definición de la clase...
}

/// Comentario para la clase.
class ClasePrueba
{
    /// <exception cref="System.Exception">Ocurre cuando...</exception>
    public void HacerAlgo()
    {
        try
        {
        }
        catch (EClass)
        {
        }
    }
}

<permission>

Sintaxis

<permission cref="member">description</permission>

Parametros

cref="member": Referencia a un miembro o campo al cual se puede llamar desde el entorno de compilación actual. El compilador comprueba si el elemento de código dado existe y traduce member al nombre de elemento canónico en la salida XML. member debe aparecer entre comillas dobles (" ").

description: Descripción del acceso al miembro.

Observaciones

La etiqueta <permission> le permite documentar el acceso de un miembro. La clase PermissionSet le permite especificar el acceso a un miembro.

Ejemplo

/// <summary>
/// Texto para la clase ClasePrueba.
/// </summary>
class ClasePrueba
{
    /// <permission cref="System.Security.PermissionSet">Todos pueden acceder a este método.</permission>
    public static void Test()
    {
    }

    static void Main()
    {
    }
}

<typeparam>

Sintaxis

<typeparam name="name">description</typeparam>

Parametros

name: El nombre del parámetro de tipo. Ponga el nombre entre comillas dobles (" ").

description: Una descripción del parámetro de tipo.

Observaciones

La etiqueta <typeparam> debe usarse en el comentario de una declaración de método o tipo genérico para describir un parámetro de tipo. Agregue una etiqueta para cada parámetro de tipo del tipo o método genérico.

El texto de la etiqueta <typeparam> se mostrará IntelliSense, en el reporte Code Comment Web de la ventana del Object Browser.

Ejemplo

/// Comentarios para la clase.
public class ClasePrueba
{
    /// <summary>
    /// Crea un nuevo arreglo de tipos arbitrarios <typeparamref name="T"/>
    /// </summary>
    /// <typeparam name="T">El tipo de elemento del arreglo.</typeparam>
    public static T[] mkArray<T>(int n)
    {
        return new T[n];
    }
}

<include>

Sintaxis

<include file='filename' path='tagpath[@name="id"]' />

Parametros

filename: El nombre del archivo XML que contiene la documentación. El nombre de archivo se puede calificar con una ruta de acceso. Incluya filename entre comillas simples (' ').

tagpath: La ruta de acceso de las etiquetas de filename que conduce a la etiqueta name. Incluya la ruta de acceso entre comillas simples (' ').

name: El especificador de nombre en la etiqueta que precede a los comentarios; name tendrá un id.

id: El identificador de la etiqueta que precede a los comentarios. Ponga el identificador entre comillas dobles (" ").

Observaciones

La etiqueta <include> le permite hacer referencia a comentarios colocados en otro archivo que describen los tipos y miembros en el código fuente. Esto es una alternativa a colocar los comentarios de documentación directamente en el archivo de código fuente. Al colocar la documentación en un archivo independiente, puede aplicar el control de código fuente a la documentación de forma independiente desde el código fuente. Una persona puede tener el archivo de código fuente extraído del repositorio y otra persona puede tener el archivo de documentación extraído del repositorio.

La etiqueta <include> usa la sintaxis de XPath de XML. Consulte la documentación de XPath para ver formas de personalizar el uso de <include>.

Ejemplo

Este es un ejemplo de múltiples archivos. El primer archivo, que usa <include>, se menciona a continuación:

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Prueba
{
    static void Main()
    {
    }
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Prueba2
{
    public void Prueba()
    {
    }
}

El segundo archivo, xml_include_tag.doc, contiene los siguientes comentarios de documentación:

<MyDocs>

<MyMembers name="test">  
<summary>  
The summary for this type.  
</summary>  
</MyMembers>  

<MyMembers name="test2">  
<summary>  
The summary for this other type.  
</summary>  
</MyMembers>  

</MyDocs>

<remarks>

Sintaxis

<remarks>description</remarks>

Parametros

description: Descripción del miembro.

Observaciones

La etiqueta <remarks> se usa para agregar información sobre un tipo y complementa la información especificada con <summary>. Esta información se muestra en la ventana Objects Browser.

Ejemplo

/// <summary>
/// Tienes una iormación principal acerca de esta clase.
/// </summary>
/// <remarks>
/// Tienes información adicional acerca de esta clase.
/// </remarks>
public class ClasePrueba
{
    /// Texto para Main
    static void Main()
    {
    }
}

<typeparamref>

Sintaxis

<typeparamref name="name"/>

Parametros

name: Nombre del parámetro de tipo. Ponga el nombre entre comillas dobles (" ").

Observaciones

Usa esta etiqueta para permitir que los consumidores del archivo de documentación den formato a la palabra de alguna manera distinta, por ejemplo en cursiva.

Ejemplo

/// Comentarios para la clase.
public class ClasePrueba
{
    /// <summary>
    /// Crea un nuevo arreglo de tipo generico <typeparamref name="T"/>
    /// </summary>
    /// <typeparam name="T">El tipo de elemento de el arreglo.</typeparam>
    public static T[] mkArray<T>(int n)
    {
        return new T[n];
    }
}

Sintaxis

<list type="bullet" | "number" | "table">  
    <listheader>  
        <term>term</term>  
        <description>description</description>  
    </listheader>  
    <item>  
        <term>term</term>  
        <description>description</description>  
    </item>  
</list>

Parametros

term: Término que se define en description.

description: Elemento de una lista numerada o con viñetas, o definición de un term.

Observaciones

El bloque <listheader> se usa para definir la fila de encabezado de una tabla o de una lista de definiciones. Cuando se define una tabla, solo es necesario suministrar una entrada para un término en el encabezado.

Cada elemento de la lista se especifica con un bloque <item>. Cuando se crea una lista de definiciones, se deberán especificar tanto term como description. En cambio, para una tabla, lista con viñetas o lista numerada, solo es necesario suministrar una entrada para description.

Una lista o una tabla pueden tener tantos bloques <item> como sean necesarios.

Ejemplo

/// Texto para la clase ClasePrueba.
public class ClasePrueba
{
    /// <summary>Este es un ejemplo de una lista con viñeta:
    /// <list type="bullet">
    /// <item>
    /// <description>Elemento 1.</description>
    /// </item>
    /// <item>
    /// <description>Elemento 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    static void Main()
    {
    }
}

<returns>

Sintaxis

<returns>description</returns>

Parametros

description: Descripción del valor devuelto.

Observaciones

La etiqueta <returns> debe usarse en el comentario de una declaración de método para describir el valor devuelto.

Ejemplo

/// Texto para la clase ClasePrueba.
public class ClasePrueba
{
    /// <returns>Devuelve cero.</returns>
    public static int GetZero()
    {
        return 0;
    }
}

<value>

Sintaxis

<value>property-description</value>

Parametros

property-description: Una descripción de la propiedad.

Observaciones

La etiqueta <value> le permite describir el valor que representa una propiedad. Ten en cuenta que cuando agrega una propiedad mediante un asistente de código en el entorno de desarrollo .NET de Visual Studio, agregará una etiqueta <summary> para la nueva propiedad. Después, debes agregar manualmente una etiqueta <value> para describir el valor que representa esa propiedad.

Ejemplo

/// Definición de la clase Empleado.
public class Empleado
{
    private string _nombre;

    /// <summary>La propiedad Nombre representa el nombre del empleado.</summary>
    /// <value>La propiedad nombre obtiene/devuelve el valor de string de la variable, _nombre.</value>
    public string Nombre
    {
        get
        {
            return _nombre;
        }
        set
        {
            _nombre = value;
        }
    }
}

Comentarios de documentación XML

Etiquetas recomendadas para los comentarios de documentación XML

Etiquetas

<c>

Sintaxis

Parametros

Observaciones

Ejemplo

<para>

Sintaxis

Parametros

Observaciones

Ejemplo

<see>

Sintaxis

Parametros

Observaciones

Ejemplo

<code>

Sintaxis

Parametros

Observaciones

Ejemplo

<param>

Sintaxis

Parametros

Observaciones

Ejemplo

<seealso>

Sintaxis

Parametros

Observaciones

Ejemplo

<example>

Sintaxis

Parametros

Observaciones

Ejemplo

<paramref>

Sintaxis

Parametros

Observaciones

Ejemplo

<summary>

Sintaxis

Parametros

Observaciones

Ejemplo

<exception>

Sintaxis

Parametros

Observaciones

Ejemplo

<permission>

Sintaxis

Parametros

Observaciones

Ejemplo

<typeparam>

Sintaxis

Parametros

Observaciones

Ejemplo

<include>

Sintaxis

Parametros

Observaciones

Ejemplo

<remarks>

Sintaxis

Parametros

Observaciones

Ejemplo

<typeparamref>

Sintaxis

Parametros

Observaciones

Ejemplo

<list>

Sintaxis