Delimitatori per i tag della documentazione (Guida per programmatori C#)
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:
///
Delimitatore di singola riga. Si tratta del formato riportato negli esempi della documentazione e utilizzato per i modelli dei progetti Visual C#. Se dopo il delimitatore è presente un carattere di spazio vuoto, quest'ultimo non è incluso nell'output XML.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 determinate regole di formattazione.
Sulla riga contenente il delimitatore /** se la parte restante della riga è rappresentata da uno spazio vuoto, la riga non viene elaborata per i commenti. Se il primo carattere dopo il delimitatore /** è uno spazio vuoto, tale spazio vuoto 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.
Se sulla riga contenente il delimitatore */ sono presenti solo spazi vuoti 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 criteri comuni all'inizio di ogni riga. Il modello può essere costituito da uno spazio vuoto facoltativo e un asterisco (*), seguiti da altri spazi vuoti facoltativi. Se trova un modello comune all'inizio di ogni riga che non inizia con il delimitatore /** o */, il compilatore ignora tale modello per ogni riga.
Negli esempi seguenti vengono illustrate queste regole.
La sola parte del commento riportato di seguito che verrà elaborata è la riga che inizia con <summary>. I tre formati di tag producono gli stessi commenti.
/** <summary>text</summary> */ /** <summary>text</summary> */ /** * <summary>text</summary> */Il compilatore identifica il modello comune " * " all'inizio della seconda e della terza riga. Il modello non è incluso nell'output.
/** * <summary> * text </summary>*/Il compilatore non trova alcun modello comune nel commento seguente poiché il secondo carattere nella terza riga non è un asterisco. Di conseguenza, tutto il testo contenuto nella seconda e nella terza riga viene elaborato come parte del commento.
/** * <summary> text </summary> */Nel seguente commento non viene rilevato alcun criterio per due motivi. Anzitutto, il numero di spazi prima dell'asterisco non è coerente. Inoltre, la quinta riga inizia con una tabulazione, che non corrisponde agli spazi. Di conseguenza, tutto il testo dalla seconda alla quinta riga verrà elaborato come parte del commento.
/** * <summary> * text * text2 * </summary> */
Vedere anche
Riferimenti
Commenti relativi alla documentazione XML (Guida per programmatori C#)
/doc (opzioni del compilatore C#)
Commenti relativi alla documentazione XML (Guida per programmatori C#)