Compartir vía

Insertar comentarios XML para la generación de documentación

  • Artículo

Este artículo describe cómo Visual Studio puede ayudarte a documentar elementos de código (como las clases y los métodos) al generar automáticamente la estructura de comentarios de documentación XML estándar. En tiempo de compilación, puede generar un archivo XML que contenga los comentarios de documentación.

Puedes distribuir el archivo XML generado por el compilador junto con el ensamblado .NET, de modo que Visual Studio y otros IDE puedan usar IntelliSense para mostrar información rápida sobre los tipos y los miembros. También puedes ejecutar el archivo XML mediante herramientas como DocFX y Sandcastle para generar sitios web de referencia de API.

Nota:

El comando Insertar comentario, que inserta automáticamente comentarios de documentación XML, está disponible en C# y Visual Basic. En el caso de C++, puedes insertar manualmente comentarios de documentación XML en archivos de C++ y seguir generando archivos de documentación XML en tiempo de compilación.

Habilitación de la generación de documentación

Para habilitar la generación de documentación, selecciona la casilla Generar un archivo que contiene la documentación de la API en la pestaña Compilación>Salida de las propiedades del proyecto.

De forma predeterminada, se genera un archivo de documentación denominado igual que el ensamblado con una extensión de archivo .xml en el mismo directorio que el ensamblado. Si deseas configurar un nombre o ubicación no predeterminado para el archivo, escribe o busca una ubicación alternativa en la ruta de acceso del archivo de documentación XML.

Para habilitar la generación de documentación, selecciona la casilla Generar un archivo de documentación XML en la pestaña Compilación>Salida de las propiedades del proyecto.

De forma predeterminada, se genera un archivo de documentación denominado igual que el ensamblado con una extensión de archivo .xml en el mismo directorio que el ensamblado. Si deseas configurar un nombre o ubicación no predeterminado para el archivo, escribe o busca una ubicación alternativa.

Como alternativa, puedes agregar las propiedades GenerateDocumentationFile o DocumentationFile al archivo .csproj, .vbproj o .fsproj. Establece GenerateDocumentationFile en true para generar un archivo de documentación con el nombre y la ubicación predeterminados. Usa la propiedad DocumentationFile para especificar otro nombre o ubicación.

Si usas DocumentationFile por sí mismo o con la propiedad GenerateDocumentationFile establecida en true, se generará un archivo de documentación con el nombre y la ubicación especificados. Sin embargo, si estableces GenerateDocumentationFile en false, no se generará ningún archivo de documentación aunque establezcas la propiedad DocumentationFile.

Habilitación del acceso directo de teclado de inserción de comentarios

Puedes establecer la opción Comentarios para insertar automáticamente estructuras de comentarios XML después de escribir /// en C# o ''' en Visual Basic.

  1. En la barra de menús de Visual Studio, elija Herramientas>Opciones.
  2. En el cuadro de diálogo Opciones, elige Editor de texto>C# (o Visual Basic) >Avanzado.
  3. En la sección Comentarios, selecciona o anula la selección Generar comentarios de documentación XML para \\\ (o ''').

Inserción automática de un comentario XML

  1. En Visual Studio, sitúa el cursor de texto sobre el elemento que deseas documentar; por ejemplo, un método.

  2. Realice una de las siguientes acciones:

    • Si el acceso directo de inserción automática de comentarios está habilitado, escribe /// en C# o ''' en Visual Basic.
    • En el menú Edición, elige IntelliSense>Insertar comentario.
    • Desde el menú contextual o al hacer clic con el botón derecho, elige Fragmento de código>Insertar comentario.

    La estructura de comentarios XML se genera inmediatamente encima del elemento de código. Por ejemplo, al comentar el siguiente método GetUserName, la plantilla genera el elemento <summary>, un elemento <param> para cada parámetro y un elemento <returns> para documentar el valor devuelto.

    /// <summary>
/// 
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public string GetUserName(int id)
{
    return "username";
}

    ''' <summary>
''' 
''' </summary>
''' <param name="id"></param>
''' <returns></returns>
Public Function GetUserName(id As Integer) As String
    Return "username"
End Function

  3. Escribe una descripción de cada elemento XML para que el código esté completamente documentado. Por ejemplo:

     /// <summary>
 /// Gets the username associated with the specified ID.
 /// </summary>
 /// <param name="id">The unique user ID.</param>
 /// <returns>A string containing the username for the specified ID.</returns>
 public string GetUserName(int id)
 {
     return "username";
 }

Puedes usar elementos XML y estilos en los comentarios que se representarán en Información rápida al mantener el ratón sobre el elemento. Estos elementos incluyen los estilos de cursiva o negrita, listas numeradas o con viñetas, y cref en los que se pueden o enlaces href.

Por ejemplo, escribe el código siguiente en un archivo de programa de C#:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Al mantener el puntero sobre GetUserName, el panel Información rápida aparece de la siguiente manera:

Captura de pantalla en la que se muestra el comentario completado con etiquetas de estilo para un vínculo en el que se puede hacer clic, una lista numerada, cursiva y negrita.

Contenido relacionado