Condividi tramite

Inserire commenti XML per la generazione di documentazione

  • Articolo

Questo articolo descrive in che modo Visual Studio consente di documentare elementi di codice, ad esempio classi e metodi, generando automaticamente la struttura dei commenti della documentazione XML standard. In fase di compilazione, è possibile generare un file XML che contiene i commenti in formato di documentazione.

È possibile distribuire il file XML generato dal compilatore insieme all'assembly .NET in modo che Visual Studio e altri IDE possano usare IntelliSense per visualizzare informazioni rapide su tipi e membri. È anche possibile eseguire il file XML tramite strumenti come DocFX e Sandcastle per generare siti Web di riferimento api.

Nota

Il comando Inserisci commento per inserire automaticamente la struttura dei commenti della documentazione XML è disponibile in C# e Visual Basic. Per C++, è possibile inserire manualmente commenti della documentazione XML e generare file di documentazione XML in fase di compilazione.

Abilitare la generazione della documentazione

Per abilitare la generazione della documentazione, selezionare la casella di controllo Genera un file contenente la documentazione dell'API nella scheda Output> di compilazione delle proprietà del progetto.

Per impostazione predefinita, un file di documentazione denominato uguale all'assembly con un'estensione di file .xml genera nella stessa directory dell'assembly. Se si vuole configurare un nome o un percorso non predefinito per il file, immettere o passare a un percorso alternativo nel percorso del file di documentazione XML.

Per abilitare la generazione della documentazione, selezionare la casella di controllo File di documentazione XML nella sezione Output> di compilazione delle proprietà del progetto.

Per impostazione predefinita, un file di documentazione denominato uguale all'assembly con un'estensione di file .xml genera nella stessa directory dell'assembly. Per configurare un nome o un percorso non predefinito per il file, immettere o passare a un percorso alternativo.

In alternativa, è possibile aggiungere le proprietà GenerateDocumentationFile o DocumentationFile al file con estensione csproj, vbproj o fsproj. Impostare GenerateDocumentationFile su true per generare un file di documentazione con il nome e il percorso predefiniti. Utilizzare la DocumentationFile proprietà per specificare un nome o una posizione diversi.

Se si usa DocumentationFile da solo o con la GenerateDocumentationFile proprietà impostata su true, viene generato un file di documentazione con il nome e il percorso specificati. Tuttavia, se si imposta su GenerateDocumentationFile false, non viene generato alcun file di documentazione anche se si imposta la DocumentationFile proprietà .

Abilitare i tasti di scelta rapida per l'inserimento di commenti

È possibile impostare l'opzione Commenti per inserire automaticamente strutture di commento XML dopo aver digitato /// in C# o ''' in Visual Basic.

  1. Nella barra dei menu di Visual Studio scegliere Opzioni strumenti>.
  2. Nella finestra di dialogo Opzioni passare a Editor>di testo C# (o Visual Basic) >Avanzate.
  3. Nella sezione Commenti selezionare o deselezionare Genera commenti della documentazione XML per \\\ (o ''').

Inserire automaticamente un commento XML

  1. In Visual Studio posizionare il cursore sopra l'elemento da documentare, ad esempio un metodo.

  2. Effettua una delle seguenti azioni:

    • Se il collegamento automatico all'inserimento dei commenti è abilitato, digitare /// C# o ''' in Visual Basic.
    • Scegliere IntelliSense Inserisci commento dal menu Modifica.>
    • Nel menu di scelta rapida o fare clic con il pulsante destro del mouse scegliere Snippet Insert Comment (Inserisci commento).>

    La struttura di commento XML viene generata immediatamente sopra l'elemento di codice. Ad esempio, quando si commenta il metodo seguente GetUserName , il modello genera l'elemento <summary> , un <param> elemento per il parametro e un <returns> elemento per documentare il valore restituito.

    /// <summary>
/// 
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public string GetUserName(int id)
{
    return "username";
}

    ''' <summary>
''' 
''' </summary>
''' <param name="id"></param>
''' <returns></returns>
Public Function GetUserName(id As Integer) As String
    Return "username"
End Function

  3. Immettere le descrizioni per ogni elemento XML per documentare completamente il codice. Ad esempio:

     /// <summary>
 /// Gets the username associated with the specified ID.
 /// </summary>
 /// <param name="id">The unique user ID.</param>
 /// <returns>A string containing the username for the specified ID.</returns>
 public string GetUserName(int id)
 {
     return "username";
 }

È possibile usare elementi e stili XML nei commenti che vengono visualizzati in Informazioni rapide quando si passa il puntatore del mouse sul codice. Questi elementi includono stili corsivo o grassetto, elenchi puntati o numerati e collegamenti selezionabili o href selezionabilicref.

Ad esempio, immettere il codice seguente in un file di programma C#:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Quando si passa il puntatore del mouse su GetUserName, il riquadro Informazioni rapide viene visualizzato come segue:

Screenshot che mostra il commento completato con tag di stile per un collegamento selezionabile, un elenco numerato e una formattazione in corsivo e grassetto.

Contenuto correlato