Tag XML consigliati per i commenti della documentazione C#

  • Articolo
  • 12 minuti per la lettura

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 codice XML valido nei commenti della documentazione. Il compilatore C# copia questi elementi nel file XML di output. Sebbene sia possibile usare qualsiasi codice XML valido nei commenti (incluso qualsiasi elemento HTML valido), la documentazione del codice è consigliata per molti motivi.

Di seguito sono riportati alcuni consigli, scenari di casi d'uso generali e aspetti che è necessario conoscere quando si usano tag di documentazione XML nel codice C#. Anche se è possibile inserire qualsiasi tag nei commenti della documentazione, questo articolo descrive i tag consigliati per i costrutti di linguaggio più comuni. In tutti i casi, è consigliabile attenersi a queste raccomandazioni:

  • Ai fini della coerenza, è necessario documentare tutti i tipi visibili pubblicamente e i relativi membri pubblici.
  • I membri private possono anche essere documentati con commenti XML. Tuttavia, espone il funzionamento interno (potenzialmente riservato) della libreria.
  • Il minimo necessario è che i tipi e i loro membri abbiano i tag <summary> perché il loro contenuto è necessario per IntelliSense.
  • 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 un'unica voce per ogni tipo.

La documentazione XML inizia con ///. Quando si crea un nuovo progetto, nei modelli vengono automaticamente inserite /// alcune linee di base. L'elaborazione di questi commenti presenta alcune restrizioni:

  • La documentazione deve essere in codice XML ben formato. Se il formato del codice XML non è corretto, il compilatore genera un avviso. Il file di documentazione conterrà un commento che indica che è stato rilevato un errore.
  • Alcuni tag consigliati hanno un significato speciale:
    • Il <param> tag 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 non riesce, 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 non riesce, il compilatore genera un avviso. Il compilatore rispetta eventuali istruzioni using quando esegue la ricerca di un tipo descritto nell'attributo cref.
    • Il <summary> tag viene usato da IntelliSense all'interno Visual Studio per visualizzare informazioni aggiuntive su un tipo o 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, usare il file di documentazione insieme alla reflection sul tipo o sul membro effettivo.

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

Alcuni dei tag consigliati possono essere usati in qualsiasi elemento di linguaggio. Altri hanno un utilizzo più specializzato. Infine, alcuni dei 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 intelliSense per i tag verificati dal compilatore e tutti i tag seguiti da ** nell'elenco seguente. Oltre ai tag elencati di seguito, il compilatore e Visual Studio convalidare i tag <b>, <i><u>, <br/>, e <a> . Il compilatore convalida anche <tt>, che è il codice HTML deprecato.

Nota

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

Se si desidera che le parentesi uncinate vengano visualizzate nel testo di un commento alla documentazione, usare la codifica HTML <>di e , che è &lt; rispettivamente e &gt; . Questa codifica è illustrata nell'esempio seguente.

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

Tag generali

<summary>

<summary>description</summary>

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

<remarks>

<remarks>
description
</remarks>

Il <remarks> tag viene usato per aggiungere informazioni su un tipo o un membro del tipo, integrando le informazioni specificate con <remarks>. Queste informazioni vengono visualizzate nella finestra Visualizzatore oggetti. Questo tag può includere spiegazioni più lunghe. Si potrebbe scoprire che l'uso CDATA di sezioni per markdown rende la scrittura più pratica. Strumenti come docfx elaborano il testo markdown nelle sezioni.

Membri del documento

<returns>

<returns>description</returns>

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

<param>

<param name="name">description</param>
  • name: nome di un parametro del metodo. Racchiudere il nome tra virgolette doppie (" "). I nomi dei parametri devono corrispondere alla firma dell'API. Se uno o più parametri non vengono trattati, 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 <param> tag deve essere usato nel commento per una dichiarazione di metodo per descrivere uno dei parametri per il metodo. Per documentare più parametri, usare più <param> tag. Il testo del <param> tag viene visualizzato in IntelliSense, nel Visualizzatore oggetti e nel report Web commenti codice.

<paramref>

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

Il <paramref> tag consente di indicare che una parola nei commenti del codice, ad esempio in <summary><remarks> un blocco o , 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 a 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 <exception> tag consente di specificare quali eccezioni possono essere generate. Questo tag può essere applicato alle definizioni di metodi, proprietà, eventi e indicizzatori.

<value>

<value>property-description</value>

Il <value> tag consente di descrivere il valore rappresentato da una proprietà. Quando si aggiunge una proprietà tramite la creazione guidata codice nell'Visual Studio di sviluppo .NET, viene aggiunto un tag di> riepilogo per la nuova proprietà. Aggiungere manualmente un <value> tag per descrivere il valore rappresentato dalla proprietà .

Formattare l'output della documentazione

<para>

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

Il <para> tag può essere utilizzato all'interno di un tag, <para><> osservazioni o valori restituiti, e consente di aggiungere struttura al testo. Il <para> tag crea un paragrafo con doppio spazio. Usare il <br/> tag se si vuole un singolo paragrafo con spazi.

<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 <listheader> blocco viene usato per definire la riga di intestazione di una tabella o di un elenco di definizioni. Quando si definisce una tabella, è necessario specificare solo una voce per term nell'intestazione. Ogni elemento dell'elenco viene specificato con un <item> blocco . 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. Un elenco o una tabella può avere tutti i <item> blocchi necessari.

<c>

<c>text</c>

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

<code>

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

Il <code> tag 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.

<example>

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

Il <example> tag 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 .

Riutilizzare il testo della documentazione

<inheritdoc>

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

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

  • cref: specificare il membro da cui ereditare la documentazione. I tag già definiti nel membro corrente non vengono sottoposti a override da quelli ereditati.
  • path: query dell'espressione XPath che restituisce 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 nelle classi di implementazione. 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 contenente la documentazione. Il nome file può essere qualificato con un percorso relativo al file del codice sorgente. Racchiudere filename tra virgolette singole (' ').
  • tagpath: percorso dei tag in filename che porta al tag name. Racchiudere il percorso tra virgolette singole (' ').
  • name: identificatore del nome nel tag che precede i commenti. name avrà un oggetto id.
  • id: ID del tag che precede i commenti. Racchiudere l'ID tra virgolette doppie (" ").

Il <include> tag consente di fare riferimento ai commenti in un altro file che descrivono i tipi e i membri nel codice sorgente. L'inclusione di un file esterno è un'alternativa all'inserimento di commenti alla 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. Il file del codice sorgente può essere estratto da una persona e il file della documentazione può essere estratto da un altro utente. Il <include> tag utilizza la sintassi XPath XML. Per informazioni su come personalizzare l'uso, vedere la documentazione di <include> XPath.

<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 la chiamata 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 specificare testo di collegamento diverso per un "cref", usando un tag di chiusura separato.
  • href="link": collegamento selezionabile a un DETERMINATO URL. Ad esempio, <see href="https://github.com">GitHub</see> produce un collegamento selezionabile con testo GitHub che si collega a https://github.com.
  • langword="keyword": parola chiave del linguaggio, ad true esempio o una delle altre parole chiave langword="keyword".

Il <see> tag consente di specificare un collegamento dall'interno del 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 di documentazione per gli elementi di codice. 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 la chiamata 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 DETERMINATO URL. Ad esempio, <seealso href="https://github.com">GitHub</seealso> produce un collegamento selezionabile con testo GitHub che si collega a https://github.com.

Il <seealso> tag consente di specificare il testo che potrebbe essere necessario visualizzare in una <seealso> anche. Usare see per> specificare un collegamento dall'interno del testo. Non è possibile annidare il seealso tag all'interno del summary tag .

Attributo cref

L'attributo cref in un tag di documentazione XML significa "riferimento al codice". Specifica che il testo 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 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 sull'API o sulla 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 del <typeparam> tag 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 descritti in precedenza rappresentano i tag riconosciuti dal compilatore C#. Gli utenti comunque possono definire tag personalizzati. Strumenti come Sandcastle supportano tag aggiuntivi >> e supportano anche <. Con i tag standard è anche possibile usare strumenti di generazione di documentazione personalizzati o all'interno dell'organizzazione e possono essere supportati più formati di output da HTML a PDF.