C# Language
Documentación XML Comentarios

Observaciones

Anotación de método simple

Los comentarios de la documentación se colocan directamente sobre el método o la clase que describen. Comienzan con tres barras diagonales /// , y permiten que la información meta se almacene a través de XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Visual Studio y otras herramientas pueden utilizar la información dentro de las etiquetas para proporcionar servicios como IntelliSense:

Vea también la lista de etiquetas comunes de documentación de Microsoft .

Comentarios de interfaz y documentación de clase.

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Resultado

Resumen de la interfaz

Resumen de la clase

Documentación del método comentar con param y devuelve elementos.

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense le muestra la descripción de cada parámetro:

Consejo: si Intellisense no se muestra en Visual Studio, elimine el primer corchete o coma y luego vuelva a escribirlo.

Generando XML a partir de comentarios de documentación.

Para generar un archivo de documentación XML a partir de los comentarios de la documentación en el código, use la opción /doc con el compilador csc.exe C #.

En Visual Studio 2013/2015, en Proyecto -> Propiedades -> Generar -> Salida , marque la casilla de verificación del XML documentation file :

Cuando compile el proyecto, el compilador producirá un archivo XML con un nombre que corresponde al nombre del proyecto (por ejemplo, XMLDocumentation.dll -> XMLDocumentation.xml ).

Cuando use el ensamblaje en otro proyecto, asegúrese de que el archivo XML esté en el mismo directorio que la DLL a la que se hace referencia.

Este ejemplo:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Produce este xml en la compilación:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Haciendo referencia a otra clase en documentación

La etiqueta <see> se puede utilizar para vincular a otra clase. Contiene el miembro cref que debe contener el nombre de la clase a la que se va a hacer referencia. Visual Studio proporcionará Intellsense al escribir esta etiqueta y dichas referencias se procesarán al cambiar el nombre de la clase a la que se hace referencia, también.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

En las ventanas emergentes de Visual Studio Intellisense, estas referencias también se mostrarán en color en el texto.

Para hacer referencia a una clase genérica, use algo similar a lo siguiente:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}