Etiquetas XML recomendadas para los comentarios de la documentación de C#

  • Artículo

Los comentarios de la documentación de C# usan elementos XML para definir la estructura de la documentación de salida. Una consecuencia de esta característica es que resulta posible agregar cualquier XML válido en los comentarios de la documentación. El compilador de C# copia estos elementos en el archivo XML de salida. Aunque puede usar cualquier XML válido en los comentarios (incluido cualquier elemento HTML válido), se recomienda documentar el código por varios motivos.

A continuación se ofrecen algunas recomendaciones, escenarios generales de casos de uso y conceptos que debe conocer al usar etiquetas de documentación XML en el código de C#. Aunque puede colocar cualquier etiqueta en los comentarios de la documentación, en este artículo se describen las etiquetas recomendadas para las construcciones de lenguaje más habituales. En todos los casos, debe adaptarse a estas recomendaciones:

  • Por motivos de coherencia, se deben documentar todos los tipos públicamente visibles y sus miembros públicos.
  • Los miembros privados también se pueden documentar mediante comentarios XML, aunque esto expone el funcionamiento interno (potencialmente confidencial) de la biblioteca.
  • Como mínimo, los tipos y sus miembros deben tener una etiqueta <summary>.
  • El texto de la documentación se debe escribir con frases completas que terminen en punto.
  • Las clases parciales son totalmente compatibles, y la información de la documentación se concatena en una única entrada de cada tipo.

La documentación XML empieza con ///. Cuando se crea un proyecto, las plantillas agregan automáticamente unas líneas de inicio ///. El procesamiento de estos comentarios tiene algunas restricciones:

  • La documentación debe ser XML con formato correcto. Si el XML no tiene el formato correcto, el compilador genera una advertencia. En ese caso, el archivo de documentación contiene un comentario que indica que se ha detectado un error.
  • Algunas de las etiquetas recomendadas tienen significados especiales:
    • La etiqueta <param> se usa para describir parámetros. Si se usa, el compilador comprueba que el parámetro existe y que todos los parámetros se describen en la documentación. Si se produce un error en la comprobación, el compilador emite una advertencia.
    • El atributo cref se puede asociar a cualquier etiqueta para hacer referencia a un elemento de código. El compilador comprueba si existe este elemento de código. Si se produce un error en la comprobación, el compilador emite una advertencia. El compilador respeta todas las instrucciones using cuando busca un tipo descrito en el atributo cref.
    • IntelliSense usa la etiqueta <summary> en Visual Studio para mostrar información adicional sobre un tipo o miembro.

      Nota

      El archivo XML no proporciona información completa sobre los tipos y los miembros (por ejemplo, no contiene información de tipos). Para obtener información completa sobre un tipo o miembro, use el archivo de documentación con reflexión en el tipo o miembro reales.

  • Los desarrolladores pueden crear su propio conjunto de etiquetas, que el compilador copia en el archivo de salida.

Algunas de las etiquetas recomendadas se pueden usar en cualquier elemento de lenguaje. Otras tienen un uso más especializado. Por último, algunas de las etiquetas se usan para aplicar formato al texto de la documentación. En este artículo se describen las etiquetas recomendadas organizadas por su uso.

El compilador comprueba la sintaxis de los elementos seguidos de un solo * en la siguiente lista. Visual Studio proporciona a IntelliSense las etiquetas comprobadas por el compilador y todas las etiquetas seguidas de ** en la siguiente lista. Además de las que aparecen aquí, el compilador y Visual Studio validan las etiquetas <b>, <i>, <u>, <br/> y <a>. El compilador también valida <tt>, que es HTML en desuso.

Nota

Los comentarios de documentación no pueden aplicarse en un espacio de nombres.

Si quiere que aparezcan corchetes angulares en el texto de un comentario de la documentación, use la codificación HTML de < y >, que es &lt; y &gt;, respectivamente. Esta codificación se muestra en el ejemplo siguiente.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Etiquetas generales

<summary>

<summary>description</summary>

La etiqueta <summary> debe usarse para describir un tipo o un miembro de tipo. Use <remarks> para agregar información adicional a una descripción de tipo. Use el atributo cref para permitir que herramientas de documentación como DocFX y Sandcastle creen hipervínculos internos a las páginas de documentación de los elementos de código. El texto de la etiqueta <summary> se muestra en IntelliSense y en la ventana Examinador de objetos.

<remarks>

<remarks>
description
</remarks>

La etiqueta <remarks> se usa para agregar información sobre un tipo o miembro de este, y complementa la información especificada con <summary>. Esta información se muestra en la ventana Examinador de objetos. Esta etiqueta puede incluir explicaciones más extensas. Puede que le resulte más cómodo escribirla con secciones CDATA para Markdown. Herramientas como docfx procesan el texto de Markdown en secciones CDATA.

Miembros del documento

<returns>

<returns>description</returns>

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

<param>

<param name="name">description</param>
  • name: nombre de un parámetro de método. Ponga el nombre entre comillas dobles (" "). Los nombres de los parámetros deben coincidir con la firma de la API. Si uno o varios parámetros no aparecen, el compilador emite una advertencia. El compilador también emite una advertencia si el valor de name no coincide con un parámetro formal de la declaración del método.

La etiqueta <param> debe usarse en el comentario de una declaración de método para describir uno de los parámetros del método. Para documentar varios parámetros, use varias etiquetas <param>. El texto de la etiqueta <param> se muestra en IntelliSense, el examinador de objetos y el informe web de comentario de código.

<paramref>

<paramref name="name"/>
  • name: nombre del parámetro al que se hace referencia. Ponga el nombre entre comillas dobles (" ").

La etiqueta <paramref> ofrece una manera de indicar que una palabra en los comentarios del código (por ejemplo, en un bloque <summary> o <remarks>) 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.

<exception>

<exception cref="member">description</exception>
  • cref = "member": 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 (" ").

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

<value>

<value>property-description</value>

La etiqueta <value> le permite describir el valor que representa una propiedad. Cuando agrega una propiedad mediante un asistente de código en el entorno de desarrollo .NET de Visual Studio, se agrega una etiqueta <summary> para la nueva propiedad. Debe agregar manualmente una etiqueta <value> para describir el valor que representa la propiedad.

Formato de salida de documentación

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

La etiqueta <para> se usa dentro de otra etiqueta, como <summary>, <remarks> o <returns>, y permite agregar estructura al texto. La etiqueta <para> crea un párrafo a doble espacio. Use la etiqueta <br/> si quiere un párrafo a un solo espacio.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

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 proporcionar una entrada para term en el encabezado. Cada elemento de la lista se especifica con un bloque <item>. Cuando se crea una lista de definiciones, es necesario 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.

<c>

<c>text</c>

La etiqueta <c> le proporciona una manera de indicar que el texto dentro de una descripción debe marcarse como código. Use <code> para indicar varias líneas como código.

<code>

<code>
    var index = 5;
    index++;
</code>

La etiqueta <code> se usa para indicar varias líneas de código. Use <c> para indicar que el texto de línea única dentro de una descripción debe marcarse como código.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

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

Reutilización de texto de documentación

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Herede comentarios XML de clases base, interfaces y métodos similares. El empleo de inheritdoc acaba con el copiado y pegado no deseados de comentarios XML duplicados y mantiene los comentarios XML sincronizados automáticamente. Tenga en cuenta que al agregar la etiqueta <inheritdoc> a un tipo, todos los miembros heredan también los comentarios.

  • cref: especifica el miembro del que se hereda la documentación. Las etiquetas ya definidas en el miembro actual no las invalidan las heredadas.
  • path: consulta de expresión XPath que genera un conjunto de nodos para mostrar. Puede usar este atributo para filtrar las etiquetas que se van a incluir o excluir en la documentación heredada.

Agregue los comentarios XML en las clases base o las interfaces y deje que inheritdoc copie los comentarios en las clases en implementación. Agregue los comentarios XML a los métodos sincrónicos y deje que inheritdoc copie los comentarios en las versiones asincrónicas de los mismos métodos. Si quiere copiar los comentarios de un miembro concreto, puede usar el atributo cref para especificar el miembro.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: nombre del archivo XML que contiene la documentación. El nombre de archivo se puede calificar con una ruta de acceso relativa al archivo de código fuente. Incluya filename entre comillas simples (' ').
  • tagpath: ruta de acceso de las etiquetas de filename que conduce a la etiqueta name. Incluya la ruta de acceso entre comillas simples (' ').
  • name: especificador de nombre de la etiqueta que precede a los comentarios; name tiene un elemento id.
  • id: identificador de la etiqueta que precede a los comentarios. Ponga el identificador entre comillas dobles (" ").

La etiqueta <include> le permite hacer referencia a comentarios colocados en otro archivo que describen los tipos y miembros en el código fuente. La inclusión de un archivo externo es una alternativa a la colocación de los comentarios de la 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 haber extraído del repositorio el archivo de código fuente y otra el archivo de documentación. La etiqueta <include> usa la sintaxis XML de XPath. Consulte la documentación de XPath para ver formas de personalizar el uso de <include>.

Por ejemplo, el código fuente siguiente usa la etiqueta <include> para incluir comentarios. La ruta de acceso del archivo es relativa al origen.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

El origen XML del archivo de inclusión se muestra en el ejemplo siguiente. Se estructura igual que el archivo XML generado por el compilador de C#. El archivo XML puede contener texto para varios métodos o tipos, siempre que una expresión XPath los pueda identificar.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

La salida XML de este método se muestra en el ejemplo siguiente:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Sugerencia

El equipo de .NET Runtime usa la <include> etiqueta ampliamente en su documentación. Puede ver muchos ejemplos si busca en el repositorio dotnet/runtime.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • 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 pasa member al nombre de elemento en el resultado XML. Agregue member entre comillas dobles (" "). Puede proporcionar otro texto de vínculo para "cref" mediante una etiqueta de cierre independiente.
  • href="link": vínculo interactivo a una dirección URL determinada. Por ejemplo, <see href="https://github.com">GitHub</see> genera un vínculo en el que se puede hacer clic, con texto GitHub que vincula a https://github.com.
  • langword="keyword": palabra clave de lenguaje, como true o una de las otras palabras clave válidas.

La etiqueta <see> permite especificar un vínculo desde el texto. Use <seealso> para indicar que el texto debe colocarse en una sección Consulte también. Use el atributo cref para crear hipervínculos internos a las páginas de documentación de los elementos de código. Incluya los parámetros de tipo para especificar una referencia a un tipo genérico o método, como cref="IDictionary{T, U}". Además, href es un atributo válido que actúa como un hipervínculo.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • 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 pasa member al nombre de elemento en el resultado XML. member debe aparecer entre comillas dobles (" ").
  • href="link": vínculo interactivo a una dirección URL determinada. Por ejemplo, <seealso href="https://github.com">GitHub</seealso> genera un vínculo en el que se puede hacer clic, con texto GitHub que vincula a https://github.com.

La etiqueta <seealso> permite especificar el texto que quiere que aparezca en una sección Vea también. Use <see> para especificar un vínculo desde dentro del texto. No se puede anidar la etiqueta seealso dentro de la etiqueta summary.

Atributo cref

El atributo cref de una etiqueta de documentación XML significa "referencia de código". Especifica que el texto interno de la etiqueta es un elemento de código, como un tipo, un método o una propiedad. En herramientas de documentación como DocFX y Sandcastle, use los atributos cref para generar hipervínculos a la página donde se documenta el tipo o miembro de manera automática.

Atributo href

El atributo href significa una referencia a una página web. Puede usarlo para hacer referencia directamente a la documentación en línea sobre la API o la biblioteca.

Métodos y tipos genéricos

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: nombre del parámetro de tipo. Ponga el nombre entre comillas dobles (" ").

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 muestra en IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: nombre del parámetro de tipo. Ponga el nombre entre comillas dobles (" ").

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

Etiquetas definidas por el usuario

Todas las etiquetas descritas anteriormente son las que reconoce el compilador de C#, pero el usuario puede definir sus propias etiquetas. Las herramientas como Sandcastle proporcionan compatibilidad con etiquetas adicionales, como <event> y <note>, e incluso permiten documentar espacios de nombres. También se pueden usar herramientas de generación de documentación internas o personalizadas con las etiquetas estándar, y se admiten varios formatos de salida, de HTML a PDF.