Balises XML recommandées pour les commentaires de documentation C#

  • Article

Les commentaires de documentation C# utilisent des éléments XML pour définir la structure de la documentation de sortie. L’une des conséquences de cette fonctionnalité est que vous pouvez ajouter n’importe quel code XML valide dans vos commentaires de documentation. Le compilateur C# copie ces éléments dans le fichier XML de sortie. Bien que vous puissiez utiliser n’importe quel code XML valide dans vos commentaires (y compris tout élément HTML valide), il est recommandé de documenter le code pour de nombreuses raisons.

Voici quelques recommandations, des scénarios de cas d’usage généraux et des éléments que vous devez connaître quand vous utilisez des balises de documentation XML dans votre code C#. Bien que vous puissiez placer n’importe quelles balises dans vos commentaires de documentation, cet article décrit les balises recommandées pour les constructions de langage les plus courantes. Dans tous les cas, vous devez respecter ces recommandations :

  • Par souci de cohérence, tous les types visibles publiquement et leurs membres respectifs doivent être documentés.
  • Les membres privés peuvent également être documentés à l’aide de commentaires XML. Toutefois, cela expose le fonctionnement interne (potentiellement confidentiel) de votre bibliothèque.
  • Au minimum, les types et leurs membres devraient avoir une étiquette <summary>.
  • Le texte de la documentation doit être écrit à l’aide de phrases complètes se terminant par un point.
  • Les classes partielles sont entièrement prises en charge, et les informations de documentation seront concaténées dans une seule entrée pour chaque type.

Le début de la documentation XML est symbolisé par ///. Lorsque vous créez un projet, les modèles insèrent quelques lignes de début /// pour vous. Le traitement de ces commentaires présente certaines restrictions :

  • La documentation doit être dans un format XML correct. Si le code XML n’est pas correctement formé, le compilateur génère un avertissement. Le fichier de documentation contiendra un commentaire indiquant qu’une erreur a été trouvée.
  • Certaines des balises recommandées ont des significations spéciales :
    • La balise <param> est utilisée pour décrire les paramètres. Quand elle est utilisée, le compilateur vérifie que le paramètre existe et que tous les paramètres sont décrits dans la documentation. Si la vérification échoue, le compilateur émet un avertissement.
    • L’attribut cref peut être joint à n’importe quelle balise pour référencer un élément de code. Le compilateur vérifie l’existence de cet élément de code. Si la vérification échoue, le compilateur émet un avertissement. Le compilateur respecte toutes les instructions using lorsqu’il recherche un type décrit dans l’attribut cref.
    • La balise <summary> est utilisée par IntelliSense dans Visual Studio pour afficher des informations supplémentaires sur un type ou un membre.

      Notes

      Le fichier XML ne fournit pas des informations complètes sur le type et les membres (par exemple, il ne contient pas d’informations sur le type). Pour obtenir des informations complètes sur un type ou sur un membre, utilisez le fichier de documentation avec la réflexion sur le type ou sur le membre en question.

  • Les développeurs sont libres de créer leur propre jeu de balises. Le compilateur copie ces informations dans le fichier de sortie.

Certaines des balises recommandées peuvent être utilisées sur n’importe quel élément de langage. D’autres ont une utilisation plus spécialisée. Enfin, certaines balises sont utilisées pour mettre en forme du texte dans votre documentation. Cet article décrit les balises recommandées organisées en fonction de leur utilisation.

Le compilateur vérifie la syntaxe des éléments suivis d’un seul * dans la liste suivante. Visual Studio fournit IntelliSense pour les balises vérifiées par le compilateur et toutes les balises suivies de ** dans la liste suivante. En plus des balises répertoriées ici, le compilateur et Visual Studio valident les balises <b>, <i>, <u>, <br/> et <a>. Le compilateur valide <tt> également, qui est du code HTML déconseillé.

Notes

Il n’est pas possible d’appliquer des commentaires de documentation à un espace de noms.

Si vous voulez que des crochets angulaires apparaissent dans le texte d’un commentaire de documentation, utilisez le codage HTML de < et >, respectivement &lt; et &gt;. Ce codage est illustré dans l’exemple suivant.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Balises générales

<summary>

<summary>description</summary>

La balise <summary> doit être utilisée pour décrire un type ou un membre de type. Utilisez <remarks> pour ajouter des informations supplémentaires à une description de type. Utilisez l’attribut cref pour activer des outils de documentation, tels que DocFX et Sandcastle, afin de créer des liens hypertexte internes aux pages de documentation pour les éléments de code. Le texte de l’étiquette <summary>est affiché dans IntelliSense et dans la fenêtre du navigateur d’objets.

<remarks>

<remarks>
description
</remarks>

La balise <remarks> permet d’ajouter des informations sur un type ou un membre de type en complétant les informations spécifiées par le <résumé>. Ces informations sont affichées dans la fenêtre Explorateur d’objets. Cette balise peut inclure des explications plus longues. Vous constaterez peut-être que l’utilisation de sections CDATA pour markdown rend l’écriture plus pratique. Des outils tels que docfx traitent le texte markdown dans les sections CDATA.

Membres du document

<returns>

<returns>description</returns>

La balise <returns> doit être utilisée dans le commentaire relatif à une déclaration de méthode pour décrire la valeur renvoyée.

<param>

<param name="name">description</param>
  • name : nom d’un paramètre de méthode. Mettez le nom entre guillemets doubles (" "). Les noms des paramètres doivent correspondre à la signature d’API. Si un ou plusieurs paramètres ne sont pas couverts, le compilateur émet un avertissement. Le compilateur émet également un avertissement si la valeur de name ne correspond pas à un paramètre formel dans la déclaration de méthode.

La balise <param> doit être utilisée dans le commentaire d’une déclaration de méthode pour décrire l’un des paramètres de la méthode. Pour documenter plusieurs paramètres, utilisez plusieurs balises <param>. Le texte de la balise <param> s’affiche dans IntelliSense, dans la fenêtre Explorateur d’objets et dans le rapport web de commentaire de code.

<paramref>

<paramref name="name"/>
  • name : nom du paramètre auquel faire référence. Mettez le nom entre guillemets doubles (" ").

La balise <paramref> vous offre un moyen d’indiquer qu’un mot dans les commentaires du code, par exemple dans un bloc <summary> ou <remarks>, fait référence à un paramètre. Le fichier XML peut être traité de manière à mettre en forme ce mot d’une façon particulière, par exemple en gras ou en italique.

<exception>

<exception cref="member">description</exception>
  • cref = « member » : référence à une exception qui est disponible à partir de l’environnement de compilation actuel. Le compilateur vérifie que l’exception donnée existe, et il traduit member en nom d’élément canonique dans le fichier XML de sortie. member doit apparaître entre guillemets doubles (" ").

La balise <exception> vous permet de spécifier quelles exceptions peuvent être levées. Cette balise peut être appliquée à des définitions de méthodes, de propriétés, d’événements et d’indexeurs.

<value>

<value>property-description</value>

La balise <value> vous permet de décrire la valeur représentée par une propriété. Lorsque vous ajoutez une propriété via l’assistant de code de l’environnement de développement Visual Studio .NET, il ajoute une balise <summary> pour la nouvelle propriété. Vous ajoutez manuellement une balise <value> pour décrire la valeur représentée par la propriété.

Mettre en forme la sortie de la documentation

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

La balise <para> est prévue pour une utilisation à l’intérieur d’une balise, telle que <summary>, <remarks> ou <returns>, et vous permet d’ajouter une structure au texte. La balise <para> crée un paragraphe avec interligne double. Utilisez la balise <br/> si vous souhaitez un paragraphe avec une seule interligne.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

Le bloc <listheader> est utilisé pour définir la ligne d’en-tête d’une table ou d’une liste de définitions. Au moment de définir une table, il vous suffit de fournir une entrée pour term figurant dans l’en-tête. Chaque élément de la liste est spécifié avec un bloc <item>. Au moment de créer une liste de définitions, vous devez spécifier à la fois term et description. Cependant, pour une table, une liste à puces ou une liste numérotée, il vous suffit de fournir une entrée pour description. Une liste ou une table peut comporter autant de blocs <item> que nécessaire.

<c>

<c>text</c>

La balise <c> vous permet d’indiquer que le texte d’une description doit être marqué comme étant du code. Utilisez <code> pour indiquer plusieurs lignes comme étant du code.

<code>

<code>
    var index = 5;
    index++;
</code>

La balise <code> est utilisée pour indiquer plusieurs lignes de code. Utilisez <c> pour indiquer qu’une ligne de texte d’une description doit être marquée comme étant du code.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

La balise <example> vous permet de spécifier un exemple d’utilisation d’une méthode ou de tout autre membre de la bibliothèque. Cela implique généralement l’utilisation de la balise <code>.

Réutiliser le texte de la documentation

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Héritez des commentaires XML des classes de base, des interfaces et de méthodes similaires. Utiliser inheritdoc élimine les actions de copier-coller indésirables des commentaires XML en double et maintient automatiquement les commentaires XML synchronisés. Notez que lorsque vous ajoutez la balise <inheritdoc> à un type, tous les membres héritent également des commentaires.

  • cref : spécifie le membre duquel hériter la documentation. Les balises déjà définies sur le membre actuel ne sont pas remplacées par les balises héritées.
  • path : requête d’expression XPath qui aboutira à un ensemble de nœuds à afficher. Vous pouvez utiliser cet attribut pour filtrer les balises à inclure ou exclure de la documentation héritée.

Ajoutez vos commentaires XML dans des classes de base ou des interfaces et laissez inheritdoc copier les commentaires dans les classes d’implémentation. Ajoutez vos commentaires XML à vos méthodes synchrones et laissez inheritdoc copier les commentaires dans vos versions asynchrones des mêmes méthodes. Si vous souhaitez copier les commentaires d’un membre spécifique, vous utilisez l’attribut cref pour spécifier le membre.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename : nom du fichier XML contenant la documentation. Le nom de fichier peut être qualifié avec un chemin relatif au fichier de code source. Mettez filename entre guillemets simples (' ').
  • tagpath : chemin des balises contenues dans filename qui mène à la balise name. Mettez le chemin entre guillemets simples (' ').
  • name : spécificateur de nom contenu dans la balise qui précède les commentaires. name possède un id.
  • id : ID de la balise qui précède les commentaires. Mettez l’ID entre guillemets doubles (" ").

La balise <include> vous permet de faire référence à des commentaires dans un autre fichier qui décrivent les types et les membres dans votre code source. Inclure un fichier externe constitue une solution alternative au placement direct des commentaires de la documentation dans votre fichier de code source. En plaçant la documentation dans un fichier distinct, vous pouvez appliquer un contrôle de code source à la documentation indépendamment du code source. Ainsi, une personne peut extraire le fichier de code source et une autre personne peut extraire le fichier de documentation. La balise <include> utilise la syntaxe XPath XML. Reportez-vous à la documentation de XPath pour savoir comment personnaliser votre utilisation de <include>.

Par exemple, le code source suivant utilise l’étiquette <include> pour inclure des remarques. Le chemin d’accès au fichier est relatif à la source.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

La source XML du fichier include est illustrée dans l’exemple suivant. Il est structuré de la même manière que le fichier XML généré par le compilateur C#. Le fichier XML peut contenir du texte pour plusieurs méthodes ou types, à condition qu’une expression XPath puisse les identifier.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

La sortie XML de cette méthode est illustrée dans l’exemple suivant :

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Conseil

L’équipe du runtime .NET utilise largement l’étiquette <include> dans sa documentation. Vous pouvez voir de nombreux exemples en recherchantdotnet/runtime dans le référentiel.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member" : référence à un membre ou un champ qu’il est possible d’appeler à partir de l’environnement de compilation actuel. Le compilateur vérifie que l’élément de code donné existe, et qu’il passe member au nom d’élément dans le code XML de sortie. Placez le membre entre guillemets doubles (" "). Vous pouvez fournir un texte de lien différent pour un « cref », à l’aide d’une balise fermante distincte.
  • href="link" : lien cliquable vers une URL donnée. Par exemple, <see href="https://github.com">GitHub</see> produit un lien cliquable avec du texte GitHub qui mène à https://github.com.
  • langword="keyword" : mot clé de langage, tel que true ou l’un des autres mots clés valides.

La balise <see> vous permet de spécifier un lien à partir de l’intérieur du texte. Utilisez <seealso> pour indiquer que le texte doit être placé dans une section Voir aussi. Utilisez l’attribut cref pour créer des liens hypertexte internes aux pages de documentation pour les éléments de code. Vous incluez les paramètres de type pour spécifier une référence à un type ou à une méthode générique, comme cref="IDictionary{T, U}". href est également un attribut valide qui fonctionnera comme un lien hypertexte.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member" : référence à un membre ou un champ qu’il est possible d’appeler à partir de l’environnement de compilation actuel. Le compilateur vérifie que l’élément de code donné existe, et qu’il passe member au nom d’élément dans le code XML de sortie. member doit apparaître entre guillemets doubles (" ").
  • href="link" : lien cliquable vers une URL donnée. Par exemple, <seealso href="https://github.com">GitHub</seealso> produit un lien cliquable avec du texte GitHub qui mène à https://github.com.

La balise <seealso> vous permet de spécifier le texte que vous souhaitez voir apparaître dans une section Voir aussi. Utilisez <see> pour spécifier un lien à partir de l’intérieur du texte. Vous ne pouvez pas imbriquer la balise seealso à l’intérieur de la balise summary.

cref, attribut

L’attribut cref dans une balise de documentation XML signifie « référence de code ». Il spécifie que le texte interne de la balise est un élément de code, tel qu’un type, une méthode ou une propriété. Les outils de documentation comme DocFX et Sandcastle utilisent les attributs cref pour générer automatiquement des liens hypertexte vers la page où le type ou le membre est documenté.

Attribut href

L’attribut href signifie une référence à une page web. Vous pouvez l’utiliser pour référencer directement la documentation en ligne sur votre API ou votre bibliothèque.

Types et méthodes génériques

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult : nom du paramètre de type. Mettez le nom entre guillemets doubles (" ").

La balise <typeparam> doit être utilisée dans le commentaire d’une déclaration de méthode ou de type générique pour décrire un paramètre de type. Ajoutez une balise pour chaque paramètre de type de la méthode et du type générique. Le texte de la balise <typeparam> s’affiche dans IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey : nom du paramètre de type. Mettez le nom entre guillemets doubles (" ").

Utilisez cette balise pour permettre aux consommateurs du fichier de documentation d’appliquer une mise en forme particulière au mot, par exemple l’italique.

Balises définies par l’utilisateur

Toutes les balises décrites ci-dessus représentent celles qui sont reconnues par le compilateur C#. Toutefois, un utilisateur est libre de définir ses propres balises. Des outils tels que Sandcastle permettent de prendre en charge des balises supplémentaires telles que <event> et <note>, et prennent même en charge la documentation des espaces de noms. Des outils de génération de documentation personnalisés ou internes peuvent également être utilisés avec les balises standard, et plusieurs formats de sortie, du format HTML au format PDF, peuvent être pris en charge.