Cómo: Utilizar las características de documentación XML (Guía de programación de C#)

Actualización: noviembre 2007

El siguiente ejemplo proporciona una descripción básica de un tipo documentado.

Ejemplo

// compile with: /doc:DocFileName.xml 

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member 
/// through the remarks tag</remarks>
public class TestClass
{
    /// <summary>
    /// Store for the name property</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here
    }

    /// <summary>
    /// Name property </summary>
    /// <value>
    /// A value tag is used to describe the property value</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here
        return 0;
    }
}

// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
    <assembly>
        <name>xmlsample</name>
    </assembly>
    <members>
        <member name="T:SomeClass">
            <summary>
            Class level summary documentation goes here.</summary>
            <remarks>
            Longer comments can be associated with a type or member 
            through the remarks tag</remarks>
        </member>
        <member name="F:SomeClass.m_Name">
            <summary>
            Store for the name property</summary>
        </member>
        <member name="M:SomeClass.#ctor">
            <summary>The class constructor.</summary> 
        </member>
        <member name="M:SomeClass.SomeMethod(System.String)">
            <summary>
            Description for SomeMethod.</summary>
            <param name="s"> Parameter description for s goes here</param>
            <seealso cref="T:System.String">
            You can use the cref attribute on any tag to reference a type or member 
            and the compiler will check that the reference exists. </seealso>
        </member>
        <member name="M:SomeClass.SomeOtherMethod">
            <summary>
            Some other method. </summary>
            <returns>
            Return results are described through the returns tag.</returns>
            <seealso cref="M:SomeClass.SomeMethod(System.String)">
            Notice the use of the cref attribute to reference a specific method </seealso>
        </member>
        <member name="M:SomeClass.Main(System.String[])">
            <summary>
            The entry point for the application.
            </summary>
            <param name="args"> A list of command line arguments</param>
        </member>
        <member name="P:SomeClass.Name">
            <summary>
            Name property </summary>
            <value>
            A value tag is used to describe the property value</value>
        </member>
    </members>
</doc>

Compilar el código

Para compilar el ejemplo, escriba lo siguiente en la línea de comandos:

csc XMLsample.cs /doc:XMLsample.xml

Se creará el archivo XMLsample.xml, el cual se puede ver en el explorador o con el comando TYPE.

Programación eficaz

La documentación XML empieza con ///. Cuando se crea un proyecto nuevo, el asistente agrega automáticamente algunas líneas iniciales con ///. El procesamiento de estos comentarios presenta algunas restricciones:

• La documentación debe estar en XML bien formado. Si el código XML no está bien formado, se generará un error de advertencia y el archivo de documentación incluirá un comentario en el que se mencionará el error encontrado.

• Los programadores pueden crear su propio conjunto de etiquetas. Existe un conjunto de etiquetas recomendado (vea la sección Información adicional). Algunas de las etiquetas recomendadas tienen significados especiales:

  • La etiqueta <param> se usa para describir parámetros. Cuando se utiliza, el compilador comprueba si el parámetro existe y si todos los parámetros están descritos en la documentación. Si la comprobación no tiene éxito, el compilador emite una advertencia.

  • El atributo cref se puede asociar a cualquier etiqueta para proporcionar una referencia a un elemento de código. El compilador comprobará si existe ese elemento de código. Si la comprobación no tiene éxito, el compilador emite una advertencia. El compilador respeta cualquier instrucción using cuando busca un tipo descrito en el atributo cref.

  • La etiqueta <summary> la utiliza IntelliSense, dentro de Visual Studio, para mostrar información adicional acerca de un tipo o un miembro.

    Nota:
    El archivo XML no proporciona información completa acerca del tipo y los miembros (por ejemplo, no contiene ninguna información de tipos). Para obtener información completa acerca de un tipo o miembro, el archivo de documentación debe utilizarse conjuntamente con el mecanismo de reflexión sobre el tipo o el miembro real.

Vea también

Tareas

Ejemplo XML Documentation

Conceptos

Guía de programación de C#

Referencia

/doc (Procesar comentarios de documentación) (Opciones del compilador de C#)

Comentarios de documentación XML (Guía de programación de C#)