Délimiteurs pour les balises de documentation (Guide de programmation C#)
Mise à jour : novembre 2007
Pour être utilisés, les commentaires de document XML requièrent des délimiteurs, qui indiquent au compilateur où commence et se termine un commentaire de documentation. Vous pouvez utiliser les types de délimiteurs ci-dessous avec les balises de documentation XML :
///
Il s'agit de la forme illustrée dans les exemples de documentation et utilisée par les modèles de projets Visual C#..gif "Remarque")
Remarque :L'IDE de Visual Studio inclut une fonctionnalité appelée Édition de commentaire intelligente qui insère automatiquement les balises <summary> et </summary>, et place le curseur dans ces balises lorsque vous tapez le délimiteur /// dans l'éditeur de code. Accédez à cette fonctionnalité à partir de Mise en forme, C#, Éditeur de texte, boîte de dialogue Options dans vos pages de propriétés de projet.
/** */
Séparateurs multilignes.
Certaines règles de mise en forme s'appliquent à l'utilisation des délimiteurs /** */ :
Pour la ligne qui contient le délimiteur /** , si le reste de la ligne correspond à un espace blanc, la ligne n'est pas traitée comme commentaire. Si le premier caractère est un espace blanc, il est ignoré et le reste de la ligne est traité. Sinon, tout le texte de la ligne qui suit le délimiteur /** est traité comme une partie du commentaire.
En ce qui concerne la ligne qui contient le délimiteur */ , si seul un espace blanc précède le délimiteur */, la ligne est ignorée. Sinon, le texte précédant le délimiteur */ sur la ligne est traité comme une partie du commentaire, sujet aux règles des critères spéciaux décrites dans le paragraphe suivant.
En ce qui concerne les lignes suivant celle qui commence par le délimiteur /**, le compilateur recherche une séquence commune au début de chaque ligne, consistant en un espace blanc facultatif et un astérisque (*), suivis éventuellement d'autres espaces. Si le compilateur trouve un ensemble de caractères commun au début de chaque ligne, il ignore cette séquence pour toutes les lignes suivant le délimiteur /**, jusqu'à la ligne (éventuellement incluse) qui contient le délimiteur */.
Voici quelques exemples :
La seule partie du commentaire suivant qui sera traitée est la ligne commençant par <summary>. Les deux formats de balise suivants produisent les mêmes commentaires :
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
Le compilateur applique une séquence " * " à ignorer au début des deuxième et troisième lignes.
/**
* <summary>
* text </summary>*/
Le compilateur ne trouve aucune séquence dans ce commentaire, car aucun astérisque ne figure dans la deuxième ligne. En conséquence, tout le texte des deuxième et troisième lignes, jusqu'au délimiteur */, est traité comme une partie du commentaire.
/**
* <summary>
text </summary>*/
Le compilateur ne trouve aucune séquence dans ce commentaire pour deux raisons. D'une part, aucune ligne ne commence par le même nombre d'espaces avant l'astérisque. D'autre part, la cinquième ligne commence par une tabulation, qui ne correspond pas à des espaces. En conséquence, tout le texte de la deuxième ligne au délimiteur */ est traité comme une partie du commentaire.
/**
* <summary>
* text
* text2
* </summary>
*/
Voir aussi
Tâches
Concepts
Référence
Commentaires de documentation XML (Guide de programmation C#)
/doc (Traiter les commentaires de documentation) (Options du compilateur C#)
Commentaires de documentation XML (Guide de programmation C#)