Procedura: utilizzare le funzionalità relative alla documentazione XML (Guida per programmatori C#)

Aggiornamento: novembre 2007

Nell'esempio che segue viene illustrato un semplice caso di documentazione di un tipo.

Esempio

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

Compilazione del codice

Per compilare l'esempio, digitare quanto segue nella riga di comando:

csc XMLsample.cs /doc:XMLsample.xml

Verrà creato il file XML XMLsample.xml, che sarà possibile visualizzare nel browser o mediante il comando TYPE.

Programmazione efficiente

La documentazione XML inizia con ///. Quando si crea un nuovo progetto, le procedure guidate inseriscono automaticamente alcune righe contrassegnate da ///. L'elaborazione di questi commenti è regolata da alcune restrizioni:

• La documentazione deve essere utilizzare formato XML corretto. Se il formato XML non è corretto, viene visualizzato un messaggio di avviso e nel file di documentazione viene inserito un commento per informare che si è verificato un errore.

• Gli sviluppatori sono liberi di creare set di tag personalizzati. Esiste un set di tag consigliato (vedere la sezione Ulteriori informazioni). Alcuni dei tag consigliati hanno un significato speciale:

  • Il tag <param> viene utilizzato per descrivere i parametri. Se utilizzato, il compilatore verifica l'esistenza del parametro e che tutti i parametri siano descritti nella documentazione. Se la verifica ha esito negativo, viene visualizzato un messaggio di avviso.

  • L'attributo cref può essere associato a qualsiasi tag per fornire un riferimento a un elemento del codice. Il compilatore verificherà l'esistenza dell'elemento del codice. Se la verifica ha esito negativo, viene visualizzato un messaggio di avviso. Il compilatore rispetta eventuali istruzioni using quando esegue la ricerca di un tipo descritto nell'attributo cref.

  • Il tag <summary> è utilizzato da IntelliSense in Visual Studio per visualizzare ulteriori informazioni su un tipo o membro.

    Nota:
    Il file XML non fornisce informazioni complete sul tipo e sui membri, ad esempio non contiene alcuna informazione sul tipo. Per ottenere informazioni complete su un tipo o su un membro, è necessario utilizzare il file di documentazione con reflection sul tipo o sul membro effettivo.

Vedere anche

Attività

Esempio di documentazione XML

Concetti

Guida per programmatori C#

Riferimenti

/doc (elaborazione dei commenti per la documentazione) (opzioni del compilatore C#)

Commenti relativi alla documentazione XML (Guida per programmatori C#)