Recommander des balises XML pour les commentaires de documentation C#

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), la documentation du code est recommandée 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 lorsque vous utilisez des balises de documentation XML dans votre code C#. Bien que vous puissiez placer des 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 les recommandations suivantes :

  • Pour des raisons de cohérence, tous les types visibles publiquement et leurs membres publics doivent être documentés.
  • Les membres privés peuvent également être documentés à l’aide de commentaires XML. Toutefois, il expose les travaux internes (potentiellement confidentiels) de votre bibliothèque.
  • Au minimum, les types et leurs membres doivent avoir une balise <summary>, car son contenu est nécessaire pour IntelliSense.
  • 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 sont concaténées en une seule entrée pour chaque type.

La documentation XML commence par /// . Lorsque vous créez un nouveau projet, les modèles placent des lignes de démarrage /// pour vous. Le traitement de ces commentaires présente certaines restrictions :

  • La documentation doit être dans un format XML correct. Si le XML n’est pas bien formé, le compilateur génère un avertissement. Le fichier de documentation contiendra un commentaire indiquant qu’une erreur a été rencontrée.
  • Certaines des balises recommandées ont des significations spéciales :
    • La <param> balise 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' cref attribut peut être attaché à 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 <summary> balise 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 un membre, utilisez le fichier de documentation ainsi que la réflexion sur le type ou le membre réel.

  • Les développeurs sont libres de créer leur propre jeu de balises. Le compilateur va les copier 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 le texte dans votre documentation. Cet article décrit les balises recommandées organisées par 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. outre les balises répertoriées ici, le compilateur et Visual Studio valident <b> les <i> balises,,, <u> <br/> et <a> . Le compilateur valide également <tt> , qui est déconseillé en html.

Notes

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

Si vous souhaitez que les chevrons apparaissent dans le texte d’un commentaire de documentation, utilisez l’encodage HTML de < et > , qui est &lt; et &gt; respectivement. Cet encodage 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 <summary> balise 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 les outils de documentation tels que DocFX et Sandcastle pour créer des liens hypertexte internes aux pages de documentation pour les éléments de code. Le texte de la <summary> balise est la seule source d’informations sur le type dans IntelliSense et s’affiche également dans la fenêtre de l’Explorateur d’objets.

<remarks>

<remarks>
description
</remarks>

La <remarks> balise est utilisée pour ajouter des informations sur un type ou un membre de type, en complétant les informations spécifiées avec <summary> . 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 CDATA de sections pour la démarque rend l’écriture plus pratique. Les outils tels que docfx traitent le texte de la démarque dans les CDATA sections.

Membres du document

<returns>

<returns>description</returns>

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

<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 de l’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 <param> balise 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 <param> balises. Le texte de la <param> balise s’affiche dans IntelliSense, dans l’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 <paramref> balise vous donne un moyen d’indiquer qu’un mot dans les commentaires de code, par exemple dans un <summary> <remarks> bloc ou 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 <exception> balise vous permet de spécifier les exceptions qui 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 <value> balise vous permet de décrire la valeur représentée par une propriété. quand vous ajoutez une propriété à l’aide de l’assistant code dans l’environnement de développement Visual Studio .net, elle ajoute une <summary> balise pour la nouvelle propriété. Vous ajoutez manuellement une <value> balise pour décrire la valeur représentée par la propriété.

Mettre en forme la sortie de documentation

<para>

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

La <para> balise est destinée à être utilisée à l’intérieur d’une balise, telle que <summary> , <remarks> ou <returns> , et vous permet d’ajouter une structure au texte. La <para> balise crée un paragraphe à espacement double. Utilisez la <br/> balise si vous souhaitez un paragraphe à espacement unique.

<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 <listheader> bloc est utilisé pour définir la ligne d’en-tête d’une table ou d’une liste de définitions. Lors de la définition d’une table, il vous suffit de fournir une entrée pour term dans l’en-tête. Chaque élément de la liste est spécifié avec un <item> bloc. Lorsque vous créez 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 avoir autant de <item> blocs que nécessaire.

<c>

<c>text</c>

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

<code>

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

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

<example>

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

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

Réutiliser le texte de documentation

<inheritdoc>

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

Hériter des commentaires XML à partir des classes de base, des interfaces et des méthodes similaires. L’utilisation inheritdoc de élimine la copie et le collage indésirables de commentaires XML en double et maintient automatiquement la synchronisation des commentaires XML. Notez que lorsque vous ajoutez la <inheritdoc> balise à un type, tous les membres héritent également des commentaires.

  • cref: Spécifiez le membre à partir duquel hériter la documentation. Les balises déjà définies sur le membre actuel ne sont pas remplacées par celles héritées.
  • path: Requête d’expression XPath qui entraîne l’affichage d’un ensemble de nœuds. 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 ou des interfaces de base et laissez inheritdoc copier les commentaires vers 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 à partir d’un membre spécifique, vous devez utiliser l' cref attribut 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 d’accès aux balises dans filename qui provoque la balise name . Mettez le chemin entre guillemets simples (' ').
  • name: Spécificateur de nom dans la balise qui précède les commentaires ; name aura un id .
  • id: ID de la balise qui précède les commentaires. Mettez l’ID entre guillemets doubles (" ").

La <include> balise vous permet de faire référence aux commentaires d’un autre fichier qui décrivent les types et les membres de votre code source. L’inclusion d’un fichier externe est une alternative au placement direct de commentaires de 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. Une personne peut extraire le fichier de code source et une autre personne peut avoir extrait le fichier de documentation. La <include> balise utilise la syntaxe XML XPath. Reportez-vous à la documentation XPath pour savoir comment personnaliser votre <include> utilisation.

<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 qui est disponible pour être appelé à 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 de fermeture distincte.
  • href="link": Lien hypertexte vers une URL donnée. Par exemple, <see href="https://github.com">GitHub</see> produit un lien sur lequel un lien hypertexte est effectué avec le texte GitHub qui est lié à https://github.com .
  • langword="keyword": Mot clé de langage, tel que true .

La <see> balise vous permet de spécifier un lien à partir de 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, par exemple cref="cref="IDictionary{T, U}" . En outre, href est 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 qui est disponible pour être appelé à 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 hypertexte vers une URL donnée. Par exemple, <seealso href="https://github.com">GitHub</seealso> produit un lien sur lequel un lien hypertexte est effectué avec le texte GitHub qui est lié à https://github.com .

La <seealso> balise 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 texte. Vous ne pouvez pas imbriquer la seealso balise dans la summary balise.

cref, attribut

L’attribut cref dans une balise de documentation XML signifie « référence de code ». Il indique 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' href attribut correspond à une référence à une page Web. Vous pouvez l’utiliser pour référencer directement la documentation en ligne sur votre API ou 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 <typeparam> balise 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 les balises qui sont reconnues par le compilateur C#. Toutefois, un utilisateur est libre de définir ses propres balises. Les outils tels que Sandcastle apportent la prise en charge de balises supplémentaires comme <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 de HTML à PDF peuvent être pris en charge.