Tag XML consigliati per i commenti relativi alla documentazione C#

  • Articolo

I commenti della documentazione C# usano elementi XML per definire la struttura della documentazione di output. Una conseguenza di questa funzionalità è che è possibile aggiungere qualsiasi XML valido nei commenti della documentazione. Il compilatore C# copia questi elementi nel file XML di output. Anche se è possibile usare qualsiasi formato XML valido nei commenti (incluso qualsiasi elemento HTML valido), la documentazione del codice è consigliabile per vari motivi.

Di seguito vengono illustrati alcuni consigli, scenari di uso generale e altre operazioni che occorre conoscere quando si usano i tag nel formato documentazione XML nel codice C#. Anche se possibile inserire tag nei commenti della documentazione, questo articolo descrive i tag consigliati per i costrutti di linguaggio più comuni. In tutti i casi, è consigliabile attenersi alle raccomandazioni seguenti:

  • Per mantenere una certa coerenza, tutti i tipi visibili pubblicamente e i loro membri devono essere documentati.
  • I membri private possono anche essere documentati con commenti XML. Ciò espone tuttavia il funzionamento interno della libreria che potrebbe essere riservato.
  • Come minimo, i tipi e i relativi membri devono avere un tag <summary>.
  • Il testo della documentazione deve essere scritto usando frasi complete che terminano con un punto.
  • Le classi parziali sono completamente supportate e le informazioni sulla documentazione verranno concatenate in una singola voce per ogni tipo.

La documentazione XML inizia con ///. Quando si crea un nuovo progetto, i modelli inseriscono alcune linee /// iniziali. L'elaborazione di questi commenti presenta alcune restrizioni:

  • La documentazione deve essere in codice XML ben formato. Se il formato XML non è corretto, il compilatore genera un avviso. Il file della documentazione conterrà un commento indicante che è stato rilevato un errore.
  • Alcuni tag consigliati hanno un significato speciale:
    • Il tag <param> viene usato per descrivere i parametri. Se usato, il compilatore verifica che il parametro esista 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 fare riferimento a un elemento di codice. Il compilatore verifica l'esistenza di questo elemento. 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> è usato da IntelliSense all'interno di Visual Studio per visualizzare altre informazioni su un tipo o su un 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 un membro, è possibile usare il file della documentazione insieme al reflection sul tipo o sul membro effettivo.

  • Gli sviluppatori sono liberi di creare set di tag personalizzati. Il compilatore le copierà nel file di output.

Alcuni dei tag consigliati possono essere usati in qualsiasi elemento del linguaggio. Altri hanno un utilizzo più specifico. Infine, alcuni tag vengono usati per formattare il testo nella documentazione. Questo articolo descrive i tag consigliati organizzati in base al loro uso.

Il compilatore verifica la sintassi degli elementi seguiti da un * singolo nell'elenco seguente. Visual Studio fornisce IntelliSense per i tag verificati dal compilatore e tutti i tag seguiti da ** nell'elenco seguente. Oltre ai tag elencati qui, il compilatore e Visual Studio convalidano i tag <b>, <i>, <u>, <br/> e <a>. Il compilatore convalida anche <tt>, che è un formato HTML deprecato.

Nota

Non è possibile applicare a uno spazio dei nomi i commenti relativi alla documentazione.

Se si vuole che nel testo di un commento alla documentazione vengano visualizzate parentesi angolari, usare la codifica HTML di < e >, ovvero rispettivamente &lt; e &gt;. Questa codifica viene mostrata nell'esempio seguente.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Tag generali

<summary>

<summary>description</summary>

Il tag <summary> deve essere usato per descrivere un tipo o un membro del tipo. Utilizzare <osservazioni> per aggiungere informazioni supplementari alla descrizione di un tipo. Usare l'attributo cref per abilitare strumenti della documentazione come DocFX e Sandcastle per creare collegamenti ipertestuali interni alle pagine della documentazione per gli elementi di codice. Il testo per il tag <summary> viene visualizzato in IntelliSense e nella finestra Visualizzatore oggetti.

<remarks>

<remarks>
description
</remarks>

Il tag <remarks> viene usato per aggiungere informazioni su un tipo o un membro del tipo, integrando le informazioni con <summary>. Queste informazioni vengono visualizzate nella finestra Visualizzatore oggetti. Questo tag può includere spiegazioni più lunghe. È possibile che l'uso delle sezioni CDATAper markdown renda più conveniente la scrittura. Strumenti come docfx elaborano il testo markdown nelle sezioni CDATA.

Membri del documento

<restituisce>

<returns>description</returns>

Il tag <returns> deve essere usato nel commento della dichiarazione di metodo per descrivere il valore restituito.

<param>

<param name="name">description</param>
  • name: nome di un parametro di metodo. Racchiudere il nome tra virgolette doppie (" "). I nomi per i parametri devono corrispondere alla firma dell'API. Se uno o più parametri non sono coperti, il compilatore genera un avviso. Il compilatore genera anche un avviso se il valore di name non corrisponde a un parametro formale nella dichiarazione del metodo.

Il tag <param> viene usato nel commento di una dichiarazione di metodo per descrivere uno dei parametri del metodo. Per documentare più parametri, usare più tag <param>. Il testo per il tag <param> viene visualizzato in IntelliSense, nel Visualizzatore oggetti e nel report Web commento codice.

<paramref>

<paramref name="name"/>
  • name: nome del parametro a cui fare riferimento. Racchiudere il nome tra virgolette doppie (" ").

Il tag <paramref> consente di indicare che una parola nei commenti del codice, ad esempio in un blocco <summary> o <remarks>, fa riferimento a un parametro. È possibile elaborare il file XML in modo da formattare la parola in modo specifico, ad esempio in grassetto o in corsivo.

<exception>

<exception cref="member">description</exception>
  • cref = "member": riferimento ad un'eccezione disponibile dall'ambiente di compilazione corrente. Il compilatore controlla che l'eccezione specificata esista e converte member nel nome canonico dell'elemento nel file XML di output. member deve essere racchiuso tra virgolette doppie (" ").

Il tag <exception> consente di specificare le eccezioni che possono essere generate. Questo tag può essere applicato alle definizioni di metodi, proprietà, eventi e indicizzatori.

<value>

<value>property-description</value>

Il tag <value> consente di descrivere il valore che rappresenta una proprietà. Quando si aggiunge una proprietà tramite la procedura guidata per il codice nell'ambiente di sviluppo di Visual Studio .NET, viene aggiunto un tag <summary> per la nuova proprietà. È necessario aggiungere manualmente un tag <value> per descrivere il valore rappresentato dalla proprietà.

Formattazione dell'output della documentazione

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Il tag <para> viene usato all'interno di un tag, ad esempio <summary>, <remarks> o <returns> e consente di aggiungere struttura al testo. Il tag <para> crea un paragrafo con spaziatura doppia. Utilizzare il tag <br/> se si desidera un singolo paragrafo con spaziatura.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

Il blocco <listheader> viene usato per definire la riga di intestazione di una tabella o di un elenco di definizioni. Per definire una tabella, è sufficiente specificare una voce per term nell'intestazione. Ogni elemento dell'elenco viene specificato tramite un blocco <item>. Quando si crea un elenco di definizioni, è necessario specificare sia term che description. Per le tabelle e gli elenchi puntati o numerati, tuttavia, è sufficiente fornire una voce per description. Gli elenchi e le tabelle possono contenere un numero qualsiasi di blocchi <item>.

<c>

<c>text</c>

Il tag <c> consente di indicare che il testo all'interno di una descrizione deve essere contrassegnato come codice. Usare <code> per indicare più righe come codice.

<code>

<code>
    var index = 5;
    index++;
</code>

Il tag <code> viene usato per indicare più righe di codice. Usare <c> per indicare che il testo a riga singola all'interno di una descrizione deve essere contrassegnato come codice.

<Esempio>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Il tag <example> consente di specificare un esempio di come usare un metodo o un altro membro della libreria. Un esempio prevede in genere l'uso del tag di <codice>.

Riuso del testo della documentazione

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Ereditare i commenti XML da classi di base, interfacce e metodi simili. L'uso di inheritdoc elimina la copia indesiderata e incolla di commenti XML duplicati e mantiene automaticamente sincronizzati i commenti XML. Si noti che quando si aggiunge il tag <inheritdoc> a un tipo, tutti i membri erediteranno anche i commenti.

  • cref: specificare il membro da cui ereditare la documentazione. I tag già definiti nel membro corrente non vengono sottoposti a override da parte di quelli ereditati.
  • path: query dell'espressione XPath che comporterà un set di nodi da visualizzare. È possibile usare questo attributo per filtrare i tag da includere o escludere dalla documentazione ereditata.

Aggiungere i commenti XML nelle classi o nelle interfacce di base e consentire a inheritdoc di copiare i commenti per implementare le classi. Aggiungere i commenti XML ai metodi sincroni e consentire a inheritdoc di copiare i commenti nelle versioni asincrone degli stessi metodi. Se si desidera copiare i commenti da un membro specifico, usare l'attributo cref per specificare il membro.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: nome del file XML che contiene la documentazione. Il nome file può essere qualificato con un percorso relativo al file del codice sorgente. Racchiudere filename tra virgolette singole (' ').
  • name: percorso dei tag di tagpath che porta al tag filename. Racchiudere il percorso tra virgolette singole (' ').
  • name: identificatore del nome contenuto nel tag che precede i commenti. name ha sempre un id.
  • id: ID del tag che precede i commenti. Racchiudere l'ID tra virgolette doppie (" ").

Il tag <include> consente di fare riferimento ai commenti di un altro file per la descrizione dei tipi e dei membri del codice sorgente, L'inclusione di un file esterno è un'alternativa all'inserimento dei commenti della documentazione direttamente nel file del codice sorgente. Inserendo la documentazione in un file separato, è possibile applicare alla documentazione il controllo del codice sorgente separatamente dal codice sorgente. Una persona, ad esempio, può avere il file di codice sorgente estratto e un'altra il file della documentazione estratto. Il tag <include> usa la sintassi XML XPath. Per informazioni sulla personalizzazione dell'utilizzo di <include>, consultare la documentazione relativa a XPath.

Ad esempio, il codice sorgente seguente usa il tag <include> per includere le osservazioni. Il percorso del file è relativo all'origine.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

L'origine XML per il file di inclusione è illustrata nell'esempio seguente. È strutturato come il file XML generato dal compilatore C#. Il file XML può contenere testo per più metodi o tipi, purché un'espressione XPath possa identificarle.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

L'output XML per questo metodo è illustrato nell'esempio seguente:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Suggerimento

Il team di runtime .NET usa ampiamente il tag <include> nella documentazione. È possibile visualizzare molti esempi cercandoli nel repository dotnet/runtime.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": riferimento a un membro o a un campo disponibile per essere chiamato dall'ambiente di compilazione corrente. Il compilatore verifica l'esistenza dell'elemento di codice specificato e passa member al nome dell'elemento nel file XML di output. Racchiudere member tra virgolette doppie (" "). È possibile fornire testo di collegamento diverso per un "cref", tramite un tag di chiusura separato.
  • href="link": collegamento selezionabile a un URL specificato. Ad esempio, <see href="https://github.com">GitHub</see> produce un collegamento selezionabile con testo GitHub che collega a https://github.com.
  • langword="keyword": parola chiave del linguaggio, ad esempio true o una delle altre parole chiave valide.

Con il tag <see> è possibile specificare un collegamento nel testo. Usare <seealso> per indicare che il testo deve essere inserito in una sezione Vedere anche. Usare l'attributo cref per creare collegamenti ipertestuali interni alle pagine della documentazione per gli elementi di codice. È possibile includere i parametri di tipo per specificare un riferimento a un tipo o a un metodo generico, ad esempio cref="IDictionary{T, U}". Inoltre, href è un attributo valido che funzionerà come collegamento ipertestuale.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": riferimento a un membro o a un campo disponibile per essere chiamato dall'ambiente di compilazione corrente. Il compilatore verifica l'esistenza dell'elemento di codice specificato e passa member al nome dell'elemento nel file XML di output. member deve essere racchiuso tra virgolette doppie (" ").
  • href="link": collegamento selezionabile a un URL specificato. Ad esempio, <seealso href="https://github.com">GitHub</seealso> produce un collegamento su cui è possibile fare clic con testo GitHub che collega a https://github.com.

Il tag <seealso> consente di specificare il testo da visualizzare in una sezione Vedere anche. Usare <see> per specificare un collegamento nel testo. Non è possibile annidare il tag seealso all'interno del tag summary.

Attributo cref

L'attributo cref in un tag della documentazione XML indica un "riferimento al codice". Specifica che il testo all'interno del tag è un elemento di codice, ad esempio un tipo, un metodo o una proprietà. Gli strumenti per la creazione di documentazione, come DocFX e Sandcastle, usano attributi cref per generare automaticamente collegamenti ipertestuali alla pagina in cui è documentato il tipo o il membro.

attributo href

L'attributo href indica un riferimento a una pagina Web. È possibile usarlo per fare riferimento direttamente alla documentazione online relativa all'API o alla libreria.

Tipi e metodi generici

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: nome del parametro di tipo. Racchiudere il nome tra virgolette doppie (" ").

Il tag <typeparam> deve essere usato nel commento per una dichiarazione di tipo o metodo generico per descrivere un parametro di tipo. Aggiungere un tag per ogni parametro di tipo del tipo o del metodo generico. Il testo per il tag <typeparam> verrà visualizzato in IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: nome del parametro di tipo. Racchiudere il nome tra virgolette doppie (" ").

Usare questo tag per consentire ai consumer del file di documentazione di formattare la parola in un modo specifico, ad esempio in corsivo.

Tag definiti dall'utente

Tutti i tag specificati in precedenza rappresentano i tag riconosciuti dal compilatore C#. Gli utenti comunque possono definire tag personalizzati. Alcuni strumenti, ad esempio Sandcastle, offrono supporto per altri tag, ad esempio <event> e <note> e anche supporto per la documentazione gli spazi dei nomi. Gli strumenti di creazione della documentazione interna o personalizzata possono anche essere usati con i tag standard e con più formati di output da HTML a PDF.