insérer des commentaires XML pour la génération de documentation

Cet article décrit comment Visual Studio peut vous aider à documenter des éléments de code, comme les classes et les méthodes, en générant automatiquement la structure de commentaire de documentation XML standard. Au moment de la compilation, vous pouvez générer un fichier XML qui contient les commentaires de documentation.

Vous pouvez distribuer le fichier XML généré avec votre assembly .NET pour permettre à Visual Studio et à d’autres IDE d’utiliser IntelliSense pour afficher des informations rapides concernant les types et les membres. Vous pouvez également exécuter le fichier XML par l’intermédiaire d’outils tels que DocFX et Sandcastle pour générer des sites web de références d’API.

Activer la génération de documentation

Vous pouvez également ajouter les propriétés GenerateDocumentationFile ou DocumentationFile à votre fichier .csproj, .vbproj, ou .fsproj. Définissez la valeur GenerateDocumentationFile sur true pour générer un fichier de documentation avec le nom et l’emplacement par défaut. Utilisez la propriété DocumentationFile pour spécifier un nom ou un emplacement différent.

Si vous utilisez DocumentationFile seul ou avec la propriété GenerateDocumentationFile définie sur true, un fichier de documentation est généré avec le nom et l'emplacement spécifiés. Toutefois, si vous définissez GenerateDocumentationFile sur false, aucun fichier de documentation n'est généré, même si vous définissez la propriété DocumentationFile.

Activer le raccourci clavier d’insertion de commentaire

Vous pouvez définir l’option Commentaires pour insérer automatiquement des structures de commentaires XML après avoir saisi /// dans C# ou ''' dans Visual Basic.

1. Dans la barre de menus de Visual Studio, choisissez Outils>Options.
2. Dans la boîte de dialogue Options, naviguez jusqu’à Éditeur de texte>C# (ou Visual Basic) >Avancé.
3. Dans la section Commentaires , sélectionnez ou désélectionnez Générer des commentaires de documentation XML pour \\\ (ou ' '').

Insérer automatiquement un commentaire XML

1. Dans Visual Studio, placez votre curseur sur l’élément que vous souhaitez documenter, par exemple, une méthode.

2. Effectuez l'une des opérations suivantes :

   • Si le raccourci d’insertion automatique de commentaire est activé, saisissez /// dans C# ou ''' dans Visual Basic.
   • Dans le menu Edition, choisissez IntelliSense>Insérer un commentaire.
   • Dans le menu contextuel (clic droit), choisissez Extrait>Insérer un commentaire.

   La structure de commentaire XML est généré immédiatement au-dessus de l’élément de code. Par exemple, quand vous commentez la méthode GetUserName suivante, le gabarit génère l’élément <summary>, un élément <param> pour le paramètre, et un élément <returns> pour documenter la valeur renvoyée.

   /// <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. Entrez la description de chaque élément XML pour documenter entièrement le code. Par exemple :

    /// <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";
    }
   

Vous pouvez utiliser des éléments XML et styles dans les commentaires qui s’affichent dans Infos rapides lorsque vous déplacer votre souris sur le code. Ces éléments comprennent les styles en italique ou en gras, les listes à puces ou les listes numérotées, et les liens cliquables cref ou href.

Par exemple, saisissez le code suivant dans un fichier de programme 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";
}

Lorsque vous passez votre souris sur GetUserName, le volet Informations rapides s’affiche comme suit :

Contenu connexe

• Commentaires de documentation
• Documentation XML en Visual Basic
• Commentaires (C++)
• Documentation XML (Visual C++)
• Génération de code