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.

Remarque

La commande Insérer un commentaire pour insérer automatiquement une structure de commentaires de documentation XML est disponible en C# et en Visual Basic. Pour C++, vous pouvez insérer manuellement des commentaires de documentation XML et 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>Sortie des propriétés de votre projet.

Par défaut, un fichier de documentation portant le même nom que votre assembly avec une extension .xml est généré dans le même répertoire que l’assembly. Si vous souhaitez configurer un nom ou un emplacement autre que celui par défaut pour le fichier, saisissez ou parcourez un autre emplacement sous Chemin d’accès au fichier de documentation XML.

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