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 tels que des classes et des méthodes en générant automatiquement la structure de commentaires 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é par le compilateur avec votre assembly .NET afin que Visual Studio et d’autres IDE puissent utiliser IntelliSense pour afficher des informations rapides sur les types et les membres. Vous pouvez également exécuter le fichier XML via des outils tels que DocFX et Sandcastle pour générer des sites web de référence d’API.

Note

La commande Insérer un commentaire pour insérer automatiquement une structure de commentaire de documentation XML est disponible en C# et En Visual Basic. Pour C++, vous pouvez insérer manuellement des commentaires de documentation XML et toujours générer des fichiers de documentation XML au moment de la compilation.

Activer la génération de documentation

Pour activer la génération de documentation, cochez la case Générer un fichier contenant la documentation de l’API sous l’onglet Générer> lasortie des propriétés de votre projet.

Par défaut, un fichier de documentation ayant le même nom que votre assembly avec une extension de fichier .xml est généré dans le même répertoire que l’assembly. Si vous souhaitez configurer un nom ou un emplacement non définis pour le fichier, entrez ou accédez à un autre emplacement sous le chemin du fichier de documentation XML.

Vous pouvez également ajouter les propriétés GenerateDocumentationFile ou DocumentationFile à votre fichier .csproj, .vbproj ou .fsproj . Définissez GenerateDocumentationFile sur true pour générer un fichier de documentation avec le nom et l'emplacement par défaut. Utilisez la DocumentationFile propriété 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 portant le nom et l’emplacement spécifiés est généré. 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 tapé /// en C# ou ''' en Visual Basic.

1. Dans la barre de menus de Visual Studio, choisissez Options d’outils>.
2. Dans la boîte de dialogue Options, accédez à l’Éditeur> de texteC# (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 au-dessus de 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é, tapez /// en C# ou ''' en Visual Basic.
   • Dans le menu Modifier , choisissez IntelliSense>Insérer un commentaire.
   • Dans le menu contextuel ou cliquez avec le bouton droit , choisissez>Extrait de code Insérer un commentaire.

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

   /// <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 des descriptions pour 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 et des styles XML dans les commentaires qui s’affichent dans Les informations rapides lorsque vous pointez sur le code. Ces éléments incluent des styles italiques ou gras, des listes à puces ou numérotées, ainsi que des liens cliquables cref ou href.

Par exemple, entrez 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 pointez sur GetUserName, le volet Informations rapides s’affiche comme suit :

Contenu connexe

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