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

El ejemplo siguiente se proporciona una introducción básica de un tipo se ha documentado que.

Ejemplo

// If compiling from the command line, compile with: /doc:YourFileName.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 : TestInterface
{
    /// <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;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <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;
    }
}

/// <summary> 
/// Documentation that describes the interface goes here. 
/// </summary> 
/// <remarks> 
/// Details about the interface go here. 
/// </remarks> 
interface TestInterface
{
    /// <summary> 
    /// Documentation that describes the method goes here. 
    /// </summary> 
    /// <param name="n">
    /// Parameter n requires an integer argument. 
    /// </param> 
    /// <returns> 
    /// The method returns an integer. 
    /// </returns> 
    int InterfaceMethod(int n);
}

Compilar el código

para compilar el ejemplo, escriba la línea de comandos siguiente:

csc XMLsample.cs /doc:XMLsample.xml

Esto creará el archivo XMLsample.xml, que puede ver en el explorador o utilizando el comando VARIANT.

Programación eficaz

La documentación XML empieza con ///. Cuando se crea un nuevo proyecto, los asistentes presentan algunas líneas ///iniciales. 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á una advertencia y el archivo de documentación incluirá un comentario que indica que se encontró un error.

• Los programadores pueden crear su propio conjunto de etiquetas. Existe un conjunto de etiquetas recomendado (vea la sección de lectura de Further). 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 se produjera un error en la comprobación, 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 se produjera un error en la comprobación, 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 sobre el tipo y miembros (por ejemplo, no contiene información de tipo).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

Referencia

/doc (Opciones del compilador de C#)

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

Conceptos

Guía de programación de C#