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

La documentación XML constituye un mecanismo eficaz para documentar el código. En el ejemplo siguiente se presenta una introducción básica.

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

El siguiente archivo .xml se genera en el ejemplo anterior. Observe que los comentarios de la definición de interfaz se incluyen en la clase que implementa la interfaz.

Compilar el código

Para compilar el ejemplo, puede escribir la siguiente línea de comandos: csc XMLsample.cs /doc:XMLsample.xml.

Este comando crea el archivo XMLsample.xml, que puede verse en un explorador o de un procesador de textos.

Si lo desea, en el Explorador de soluciones, puede hacer también clic con el botón secundario en el nombre del proyecto y, a continuación, hacer clic en Propiedades. En la pestaña Compilación, seleccione Archivo de documentación XML en la sección Resultados y, a continuación, escriba un nombre para el archivo .xml.

Programación eficaz

La documentación XML empieza con ///. Cuando cree un nuevo proyecto, el IDE agregará algunas líneas /// por usted. El procesamiento de estos comentarios presenta las restricciones siguientes:

• 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 en el que se mencionará el error encontrado.

• Los desarrolladores pueden crear sus propios conjuntos de etiquetas. Sin embargo, existe un conjunto de etiquetas recomendado (consulte la sección Vea también de este tema) que tienen significados especiales, como se describe en los siguientes ejemplos:

  • La etiqueta <param> se usa para describir parámetros. Si se usa esta etiqueta, el compilador comprueba que el parámetro existe y que 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 comprueba que el elemento de código existe. 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 sobre el tipo y los miembros. Por ejemplo, no contiene ninguna información sobre el 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#

Historial de cambios