C# Language
Commenti sulla documentazione XML

Osservazioni

Annotazione semplice metodo

I commenti della documentazione vengono posizionati direttamente sopra il metodo o la classe che descrivono. Iniziano con tre barre in avanti /// e consentono la memorizzazione delle meta informazioni tramite XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Le informazioni all'interno dei tag possono essere utilizzate da Visual Studio e altri strumenti per fornire servizi come IntelliSense:

Vedi anche l'elenco di Microsoft di tag di documentazione comuni .

Commenti sulla documentazione di interfaccia e classe

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Risultato

Riepilogo dell'interfaccia

Riepilogo della classe

Commenti sulla documentazione del metodo con elementi param e resi

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense ti mostra la descrizione per ogni parametro:

Suggerimento: se Intellisense non viene visualizzato in Visual Studio, eliminare la prima parentesi o la virgola e quindi digitarlo di nuovo.

Generazione di XML dai commenti della documentazione

Per generare un file di documentazione XML dai commenti della documentazione nel codice, utilizzare l'opzione /doc con il compilatore csc.exe C #.

In Visual Studio 2013/2015, In Progetto -> Proprietà -> Crea -> Output , seleziona la casella di controllo del XML documentation file :

Quando si genera il progetto, il compilatore produrrà un file XML con un nome corrispondente al nome del progetto (ad es. XMLDocumentation.dll -> XMLDocumentation.xml ).

Quando si utilizza l'assembly in un altro progetto, assicurarsi che il file XML sia nella stessa directory della DLL a cui si fa il riferimento.

Questo esempio:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Produce questo xml su build:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Fare riferimento a un'altra classe nella documentazione

Il tag <see> può essere utilizzato per collegarsi a un'altra classe. Contiene il membro cref che dovrebbe contenere il nome della classe a cui fare riferimento. Visual Studio fornirà Intellsense durante la scrittura di questo tag e tali riferimenti verranno elaborati anche in caso di ridenominazione della classe di riferimento.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

Nei popup di Visual Studio Intellisense tali riferimenti verranno visualizzati anche colorati nel testo.

Per fare riferimento a una classe generica, utilizzare qualcosa di simile al seguente:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}