Delimitatori per i tag della documentazione (Guida per programmatori C#)
Aggiornamento: novembre 2007
L'utilizzo dei commenti XML relativi alla documentazione richiede la specifica di delimitatori per indicare al compilatore il punto di inizio e di fine di un commento relativo alla documentazione. I tipi di delimitatore utilizzabili con i tag della documentazione XML sono:
///
Si tratta del formato riportato negli esempi della documentazione e utilizzato per i modelli dei progetti Visual C#..gif "Nota")
Nota:Nell'IDE di Visual Studio è inclusa una funzionalità chiamata Modifica intelligente dei commenti che consente di inserire automaticamente i tag <summary> e </summary> e di spostare il cursore all'interno di questi tag dopo aver digitato il delimitatore /// nell'editor di codice. Tale funzione è accessibile dalla Formattazione, C#, Editor di testo, finestra di dialogo Opzioni della pagina delle proprietà del progetto.
/** */
Delimitatori su più righe.
Quando si utilizzano i delimitatori /** */, è necessario rispettare le seguenti regole di formattazione:
Per la riga contenente il delimitatore /**, se la parte restante della riga è rappresentata da uno spazio, la riga non viene elaborata per i commenti. Se il primo carattere è uno spazio, viene ignorato e il resto della riga viene elaborato. In caso contrario, l'intero testo della riga dopo il delimitatore /** viene elaborato come parte del commento.
Per la riga contenente il delimitatore */, se sono presenti solo spazi fino al delimitatore */, la riga viene ignorata. In caso contrario, il testo contenuto nella riga fino al delimitatore */ viene elaborato come parte del commento, in base alle regole dei criteri di ricerca descritte nel punto che segue.
Per le righe successive a quella che inizia con il delimitatore /**, il compilatore cerca un criterio comune all'inizio di ogni riga costituito da uno spazio facoltativo e da un asterisco (*), seguito da più spazi facoltativi. Se all'inizio di ogni riga viene rilevato un insieme comune di caratteri, il criterio verrà ignorato per tutte le righe successive al delimitatore /**, fino alla riga contenente il delimitatore */, possibilmente inclusa.
Di seguito sono riportati alcuni esempi:
La sola parte del commento riportato di seguito che verrà elaborata è la riga che inizia con <summary>. I due seguenti formati di tag produrranno gli stessi commenti:
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
Il compilatore applica un criterio costituito dal carattere " * " per ignorare il testo all'inizio della seconda e della terza riga.
/**
* <summary>
* text </summary>*/
In questo commento non vengono rilevati criteri in quanto nella seconda riga non è presente alcun asterisco. Tutto il testo contenuto nella seconda e nella terza riga, fino a */, verrà quindi elaborato come parte del commento.
/**
* <summary>
text </summary>*/
In questo commento non viene rilevato alcun criterio per i due motivi che seguono. Innanzitutto, nessuna riga inizia con un numero coerente di spazi prima dell'asterisco. Inoltre, la quinta riga inizia con una tabulazione, che non corrisponde agli spazi. Tutto il testo dalla seconda riga fino a */ verrà quindi elaborato come parte del commento.
/**
* <summary>
* text
* text2
* </summary>
*/
Vedere anche
Attività
Concetti
Riferimenti
Commenti relativi alla documentazione XML (Guida per programmatori C#)
/doc (elaborazione dei commenti per la documentazione) (opzioni del compilatore C#)
Commenti relativi alla documentazione XML (Guida per programmatori C#)