Comment échapper des caractères dans les commentaires c #?

J'ai réalisé aujourd'hui que je ne sais pas comment échapper aux caractères dans les commentaires pour C #. Je veux documenter une classe C # générique, mais je ne peux pas écrire un exemple correct car je ne sais pas comment échapper aux caractères <et >. Dois-je utiliser <et >? Je n'aime pas si c'est le cas car je veux faciliter la lecture du commentaire dans le document réel afin de ne pas avoir à générer une sorte de document de code pour pouvoir lire l'exemple de code.

Si vous avez besoin d'échapper des caractères dans les commentaires XML, vous devez utiliser les entités de caractères, vous <devrez donc les échapper comme <, comme dans votre question.

L'alternative à l'échappement consiste à utiliser des CDATAsections, au même effet.

Comme vous l'avez noté, cela produirait une belle documentation, mais un commentaire horrible à lire ...

Dans les commentaires C # simples, vous pouvez utiliser n'importe quel caractère (sauf */si vous avez commencé le commentaire avec /*, ou le caractère de nouvelle ligne si vous avez commencé le commentaire avec //). Si vous utilisez des commentaires XML, vous pouvez utiliser une section CDATA pour inclure les caractères «<» et «>».

Consultez cet article de blog MSDN pour plus d'informations sur les commentaires XML en C #.

Par exemple

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

Vous avez dit "Je veux faciliter la lecture du commentaire dans le document proprement dit". Je suis d'accord.

Les développeurs passent la majeure partie de leur vie dans le code , sans parcourir les documents générés automatiquement. Ceux-ci sont parfaits pour les bibliothèques tierces comme la création de graphiques, mais pas pour le développement en interne où nous travaillons avec tout le code. Je suis un peu choqué que MSFT n'ait pas proposé de solution qui supporte mieux les développeurs ici. Nous avons des régions qui développent / réduisent dynamiquement le code ... pourquoi ne pouvons-nous pas avoir une bascule de rendu de commentaire sur place (entre le texte brut et le commentaire XML traité ou entre le texte brut et le commentaire HTML traité)?. On dirait que je devrais avoir des capacités HTML élémentaires dans mes commentaires de prologue de méthode / classe (texte rouge, italique, etc.). Un IDE pourrait sûrement faire un peu de magie de traitement HTML pour animer les commentaires en ligne.

Ma solution de hack-of-a-solution : je change '<' en "{" et '> "en"} ". Cela semble me couvrir pour l'exemple typique de commentaire de style d'utilisation, y compris votre exemple spécifique. Imparfait, mais pragmatique étant donné le problème de lisibilité (et les problèmes de coloration des commentaires IDE qui s'ensuivent lors de l'utilisation de '<')

Les commentaires XML C # sont écrits en XML, vous utiliseriez donc un échappement XML normal.

Par exemple...

<summary>Here is an escaped &lt;token&gt;</summary>

J'ai trouvé une solution vivable à ce problème qui consiste simplement à inclure deux exemples: une version difficile à lire dans les commentaires XML avec des caractères d'échappement et une autre version lisible utilisant des //commentaires conventionnels .

Simple mais efficace.

Mieux vaut utiliser {...}, c'est utiliser ≤ ... ≥ (signe inférieur ou égal, signe supérieur ou égal, U2264 et U2265 en Unicode). On dirait des équerres soulignées, mais toujours des équerres! Et n'ajoute que quelques octets à votre fichier de code.

Encore mieux, essayez U2280 et U2281 - il suffit de copier et coller à partir de la liste des caractères Unicode (section des opérateurs mathématiques).