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

La documentazione XML fornisce un modo efficace per documentare il codice. Nell'esempio seguente viene illustrata una panoramica di base.

Esempio

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

Il file con estensione xml seguente è generato dall'esempio precedente. Si noti che i commenti della definizione di interfaccia sono inclusi nella classe che implementa l'interfaccia.

Compilazione del codice

Per compilare l'esempio, è possibile digitare la riga di comando seguente: csc XMLsample.cs /doc:XMLsample.xml.

Questo comando consente di creare il file XML XMLsample.xml, che è possibile visualizzare in un browser o in un elaboratore di testo.

In alternativa, in Esplora soluzioni fare clic con il pulsante destro del mouse sul nome del progetto, quindi scegliere Proprietà. Nella scheda Compilazione selezionare File di documentazione XML nella sezione Output e quindi immettere un nome per il file xml.

Programmazione efficiente

La documentazione XML inizia con ///. Quando si crea un nuovo progetto, tramite l'IDE vengono aggiunte alcune linee ///. L'elaborazione di questi commenti è sottoposta alle limitazioni seguenti:

• La documentazione deve utilizzare un 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 possono creare set di tag personalizzati. Vi è tuttavia un set di tag consigliato (vedere la sezione Vedere anche di questo argomento) che ha un significato speciale, come illustrato negli esempi seguenti:

  • Il tag <param> viene utilizzato per descrivere i parametri. Se questo tag viene utilizzato, il compilatore verifica l'esistenza dei parametri 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 verifica 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. Non contiene, ad esempio, 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

Riferimenti

/doc (opzioni del compilatore C#)

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

Concetti

Guida per programmatori C#

Cronologia delle modifiche