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

Nell'esempio seguente viene fornita una panoramica di base di un tipo di cui è stata documentato.

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

Compilazione del codice

Per compilare l'esempio, digitare la riga di comando seguente:

csc XMLsample.cs /doc:XMLsample.xml

Verrà creato il file XML XMLsample.xml, che è possibile visualizzare nel browser o tramite il comando di TYPE.

Programmazione efficiente

La documentazione XML inizia con ///. Quando si crea un nuovo progetto, le procedure guidate impongono alcune linee ///iniziali in per l'utente. 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 avviso viene generato l'evento e il file di documentazione conterrà 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 di un ulteriore lettura). 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, il compilatore genera un avviso.

  • L'attributo cref può essere associato a qualsiasi tag per fornire un riferimento a un elemento del codice. Il compilatore verifica dell'elemento del codice esistente. Se la verifica ha esito negativo, il compilatore genera un 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 i 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

Riferimenti

/doc (opzioni del compilatore C#)

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

Concetti

Guida per programmatori C#