Condividi tramite

Generare commenti sulla documentazione dell'API XML

I file di origine C# possono includere commenti strutturati che producono documentazione dell'API per i tipi definiti in tali file. Il compilatore C# genera un file XML che contiene dati strutturati che rappresentano i commenti e le firme API. Altri strumenti possono elaborare l'output XML per creare una documentazione leggibile sotto forma di pagine Web o file PDF, ad esempio.

Questo processo offre molti vantaggi per aggiungere la documentazione dell'API nel codice:

  • Il compilatore C# combina la struttura del codice C# con il testo dei commenti in un singolo documento XML.
  • Il compilatore C# verifica che i commenti corrispondano alle firme api per i tag pertinenti.
  • Gli strumenti che elaborano i file di documentazione XML possono definire elementi e attributi XML specifici per tali strumenti.

Strumenti come Visual Studio forniscono IntelliSense per molti elementi XML comuni usati nei commenti della documentazione.

Questo articolo illustra questi argomenti:

  • Commenti della documentazione e generazione di file XML
  • Tag convalidati dal compilatore C# e Da Visual Studio
  • Formato del file XML generato

Creare l'output della documentazione XML

È possibile creare la documentazione per il codice scrivendo campi di commento speciali indicati da barre triple. I campi di commento includono elementi XML che descrivono il blocco di codice che segue i commenti. Per esempio:

/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass { }

È possibile impostare l'opzione GenerateDocumentationFile o DocumentationFile e il compilatore trova tutti i campi di commento con tag XML nel codice sorgente e crea un file di documentazione XML da tali commenti. Quando questa opzione è abilitata, il compilatore genera l'avviso CS1591 per qualsiasi membro visibile pubblicamente dichiarato nel progetto senza commenti della documentazione XML.

Formati di commento XML

L'uso dei commenti della documentazione XML richiede delimitatori che indicano dove inizia e termina un commento della documentazione. Tu usi i seguenti delimitatori con i tag della documentazione XML:

  • /// Delimitatore a riga singola: gli esempi di documentazione e i modelli di progetto C# usano questo modulo. Se lo spazio vuoto segue il delimitatore, non viene incluso nell'output XML.

    Annotazioni

    Visual Studio inserisce automaticamente i <summary> tag e </summary> e posiziona il cursore all'interno di questi tag dopo aver digitato il /// delimitatore nell'editor di codice. È possibile attivare o disattivare questa funzionalità nella finestra di dialogo Opzioni.

  • /** */ Delimitatori su più righe: i /** */ delimitatori hanno le regole di formattazione seguenti:

    • Nella riga che contiene il /** delimitatore, se il resto della riga è vuoto, la riga non viene elaborata per i commenti. Se il primo carattere dopo il /** delimitatore è uno spazio vuoto, lo spazio vuoto viene ignorato e il resto della riga viene elaborato. Altrimenti, l'intero testo della riga dopo il delimitatore /** è elaborato come parte del commento.

    • Nella riga che contiene il */ delimitatore, se è presente solo uno spazio vuoto fino al */ delimitatore, tale riga viene ignorata. In caso contrario, il testo nella riga fino al */ delimitatore viene elaborato come parte del commento.

    • Per le righe successive a quella che inizia con il /** delimitatore, il compilatore cerca un modello comune all'inizio di ogni riga. Il modello può essere costituito da spazi vuoti facoltativi e/o da un asterisco (*), seguito da più spazi vuoti facoltativi. Se il compilatore trova uno schema comune all'inizio di ogni riga che non inizia con il delimitatore /** o termina con il delimitatore */, ignora tale schema per ogni riga.

    • L'unica parte del commento seguente 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 un modello comune di " * " 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 perché il secondo carattere nella terza riga non è un asterisco. Tutto il testo nella seconda e nella terza riga viene elaborato come parte del commento.

      /**
* <summary>
   text </summary>
*/

    • Il compilatore non trova alcun modello nel commento seguente per due motivi. Prima di tutto, il numero di spazi prima dell'asterisco non è coerente. In secondo luogo, la quinta riga inizia con una tabulazione, che non corrisponde agli spazi. Tutto il testo dalle righe da due a cinque viene elaborato come parte del commento.

      /**
  * <summary>
  * text
*  text2
 	*  </summary>
*/

Per fare riferimento agli elementi XML (ad esempio, la funzione elabora elementi XML specifici che si desidera descrivere in un commento della documentazione XML), è possibile usare il meccanismo di virgolette standard (&lt; e &gt;). Per fare riferimento agli identificatori generici negli elementi di riferimento al codice (cref), è possibile usare i caratteri di escape (ad esempio, cref="List&lt;T&gt;") o parentesi graffe (cref="List{T}"). Come caso speciale, il compilatore analizza le parentesi graffe come parentesi angolari per rendere il commento della documentazione meno complesso all'autore quando si fa riferimento a identificatori generici.

Annotazioni

Se si scrivono commenti usando il delimitatore di commento XML a riga singola, ///ma non si includono tag, il compilatore aggiunge il testo di tali commenti al file di output XML. Tuttavia, l'output non include elementi XML, come ad esempio <summary>. La maggior parte degli strumenti che usano commenti XML (incluso Visual Studio IntelliSense) non legge questi commenti.

Strumenti che accettano l'input della documentazione XML

Gli strumenti seguenti creano l'output dai commenti XML:

  • DocFX: DocFX è un generatore di documentazione API per .NET, che attualmente supporta C#, Visual Basic e F#. Consente inoltre di personalizzare la documentazione di riferimento generata. DocFX compila un sito Web HTML statico dal codice sorgente e dai file Markdown. Inoltre, DocFX offre la flessibilità necessaria per personalizzare il layout e lo stile del sito Web tramite modelli. È anche possibile creare modelli personalizzati.
  • Sandcastle: gli strumenti Sandcastle creano file della Guida per le librerie di classi gestite contenenti sia pagine di riferimento concettuali che API. Gli strumenti Sandcastle sono basati sulla riga di comando e non dispongono di funzionalità front-end gui, gestione dei progetti o processo di compilazione automatizzato. Sandcastle Help File Builder fornisce strumenti grafici autonomi e basati sulla riga di comando per creare un file della Guida in modo automatico. È disponibile anche un pacchetto di integrazione di Visual Studio affinché i progetti della guida possano essere creati e gestiti interamente all'interno di Visual Studio.
  • Doxygen: Doxygen genera un browser di documentazione online (in HTML) o un manuale di riferimento offline (in LaTeX) da un set di file di origine documentati. È disponibile anche il supporto per la generazione di output in RTF (MS Word), PostScript, PDF con collegamenti ipertestuali, HTML compresso, DocBook e pagine manuale Unix. È possibile configurare Doxygen per estrarre la struttura del codice dai file di origine non documentati.

Annotazioni

I commenti della documentazione XML non sono metadati; non sono inclusi nell'assembly compilato e pertanto non sono accessibili tramite reflection.

Stringhe ID

Ogni tipo o membro viene archiviato in un elemento nel file XML di output. Ognuno di questi elementi ha una stringa ID univoca che identifica il tipo o il membro. La stringa ID deve tenere conto di operatori, parametri, valori restituiti, parametri di tipo generico, refin, e out . Per codificare tutti questi elementi potenziali, il compilatore segue regole chiaramente definite per generare le stringhe ID. I programmi che elaborano il file XML usano la stringa ID per identificare i metadati o gli elementi di reflection .NET corrispondenti a cui si applica la documentazione.

Il compilatore osserva le regole seguenti quando genera le stringhe ID:

  • Nella stringa non sono presenti spazi vuoti.

  • La prima parte della stringa identifica il tipo di membro utilizzando un singolo carattere seguito da due punti. Vengono usati i tipi di membro seguenti:

    Personaggio Tipo di membro Note
    N Namespace Non è possibile aggiungere commenti alla documentazione a uno spazio dei nomi, ma è possibile farvi cref riferimento, se supportato.
    T tipo Un tipo è una classe, un'interfaccia, uno struct, un'enumerazione o un delegato.
    F campo
    P proprietà Include indicizzatori o altre proprietà indicizzate.
    M metodo Include metodi speciali, ad esempio costruttori e operatori.
    E evento
    ! stringa di errore Il resto della stringa fornisce informazioni sull'errore. Il compilatore C# genera informazioni sull'errore per i collegamenti che non possono essere risolti.

  • La seconda parte della stringa è il nome completo dell'elemento, a partire dalla radice dello spazio dei nomi. Il nome dell'elemento, i tipi di inclusione e lo spazio dei nomi sono separati da punti. Se il nome dell'elemento stesso ha punti, questi vengono sostituiti con il segno hash ('#'). La grammatica presuppone che nessun elemento abbia un accesso hash direttamente nel nome. Ad esempio, il nome completo del costruttore String è "System.String.#ctor".

  • Per le proprietà e i metodi, l'elenco di parametri racchiuso tra parentesi segue. Se non sono presenti parametri, non sono presenti parentesi. I parametri sono separati da virgole. La codifica di ogni parametro segue direttamente il modo in cui viene codificata in una firma .NET (vedere Microsoft.VisualStudio.CorDebugInterop.CorElementType per le definizioni di tutti gli elementi maiuscole nell'elenco seguente):

    • Tipi di base. I tipi regolari (ELEMENT_TYPE_CLASS o ELEMENT_TYPE_VALUETYPE) sono rappresentati come nome completo del tipo.
    • I tipi intrinseci ( ad esempio , ELEMENT_TYPE_I4ELEMENT_TYPE_TYPEDBYREFELEMENT_TYPE_OBJECTELEMENT_TYPE_STRING, e ELEMENT_TYPE_VOID) sono rappresentati come nome completo del tipo completo corrispondente. Ad esempio, System.Int32 o System.TypedReference.
    • ELEMENT_TYPE_PTR è rappresentato come '*' dopo il tipo modificato.
    • ELEMENT_TYPE_BYREF è rappresentato come '@' dopo il tipo modificato.
    • ELEMENT_TYPE_CMOD_OPT è rappresentato come '!' e il nome completo della classe modificatrice, seguendo il tipo modificato.
    • ELEMENT_TYPE_SZARRAY è rappresentato come "[]" dopo il tipo di elemento della matrice.
    • ELEMENT_TYPE_ARRAY è rappresentato come [limite inferiore:size,limite inferiore:size] dove il numero di virgole è il rango - 1 e i limiti e le dimensioni inferiori di ogni dimensione, se noto, sono rappresentati in decimale. Il limite inferiore e le dimensioni vengono omessi se non vengono specificati. Se il limite inferiore e le dimensioni per una determinata dimensione vengono omessi, viene omesso anche ':'. Ad esempio, una matrice bidimensionale con 1 come limiti inferiori e dimensioni non specificate è [1:,1:].

  • Solo per gli operatori di conversione (op_Implicit e op_Explicit), il valore restituito del metodo viene codificato come ~ seguito dal tipo restituito. Ad esempio: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> è il tag per l'operatore public static explicit operator int (decimal value); cast dichiarato nella System.Decimal classe .

  • Per i tipi generici, il nome del tipo è seguito da un backtick e quindi da un numero che rappresenta il conteggio dei parametri di tipo generico. Ad esempio: <member name="T:SampleClass`2"> è il tag per un tipo definito come public class SampleClass<T, U>. Per i metodi che accettano tipi generici come parametri, i parametri di tipo generico vengono specificati come numeri preceduti da backtick (ad esempio `0, `1). Ogni numero rappresenta una notazione di matrice in base zero per i parametri generici del tipo.

    • ELEMENT_TYPE_PINNED è rappresentato come '^' dopo il tipo modificato. Il compilatore C# non genera mai questa codifica.
    • ELEMENT_TYPE_CMOD_REQ è rappresentato come '|' e il nome completo della classe modificatore, dopo il tipo modificato. Il compilatore C# non genera mai questa codifica.
    • ELEMENT_TYPE_GENERICARRAY è rappresentato come "[?]" dopo il tipo di elemento della matrice. Il compilatore C# non genera mai questa codifica.
    • ELEMENT_TYPE_FNPTR è rappresentato come "=FUNC:type(signature)", dove type è il tipo restituito e la firma è gli argomenti del metodo . Se non sono presenti argomenti, le parentesi vengono omesse. Il compilatore C# non genera mai questa codifica.
    • I seguenti componenti della firma non sono rappresentati perché non vengono utilizzati per distinguere i metodi sovraccarichi.
      • convenzione di chiamata
      • tipo di ritorno
      • ELEMENT_TYPE_SENTINEL

Gli esempi seguenti illustrano come vengono generate le stringhe ID per una classe e i relativi membri:

namespace MyNamespace;

/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:MyNamespace.MyClass".
/// </summary>
public unsafe class MyClass
{
    /// <summary>
    /// Enter description here for the first constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor".
    /// </summary>
    public MyClass() { }

    /// <summary>
    /// Enter description here for the second constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public MyClass(int i) { }

    /// <summary>
    /// Enter description here for field Message.
    /// ID string generated is "F:MyNamespace.MyClass.Message".
    /// </summary>
    public string? Message;

    /// <summary>
    /// Enter description for constant PI.
    /// ID string generated is "F:MyNamespace.MyClass.PI".
    /// </summary>
    public const double PI = 3.14;

    /// <summary>
    /// Enter description for method Func.
    /// ID string generated is "M:MyNamespace.MyClass.Func".
    /// </summary>
    /// <returns>Describe return value.</returns>
    public int Func() => 1;

    /// <summary>
    /// Enter description for method SomeMethod.
    /// ID string generated is "M:MyNamespace.MyClass.SomeMethod(System.String,System.Int32@,System.Void*)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <param name="num">Describe parameter.</param>
    /// <param name="ptr">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int SomeMethod(string str, ref int num, void* ptr) { return 1; }

    /// <summary>
    /// Enter description for method AnotherMethod.
    /// ID string generated is "M:MyNamespace.MyClass.AnotherMethod(System.Int16[],System.Int32[0:,0:])".
    /// </summary>
    /// <param name="array1">Describe parameter.</param>
    /// <param name="array">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int AnotherMethod(short[] array1, int[,] array) { return 0; }

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
    /// </summary>
    /// <param name="first">Describe parameter.</param>
    /// <param name="second">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static MyClass operator +(MyClass first, MyClass second) { return first; }

    /// <summary>
    /// Enter description for property.
    /// ID string generated is "P:MyNamespace.MyClass.Prop".
    /// </summary>
    public int Prop { get { return 1; } set { } }

    /// <summary>
    /// Enter description for event.
    /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
    /// </summary>
    public event Del? OnHappened;

    /// <summary>
    /// Enter description for index.
    /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <returns></returns>
    public int this[string s] => 1;

    /// <summary>
    /// Enter description for class Nested.
    /// ID string generated is "T:MyNamespace.MyClass.Nested".
    /// </summary>
    public class Nested { }

    /// <summary>
    /// Enter description for delegate.
    /// ID string generated is "T:MyNamespace.MyClass.Del".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public delegate void Del(int i);

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
    /// </summary>
    /// <param name="myParameter">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static explicit operator int(MyClass myParameter) => 1;
}

Specifiche del linguaggio C#

Per altre informazioni, vedere l'allegato Specifica del linguaggio C# nei commenti della documentazione.