Chaîne XML dans un commentaire de résumé C #

Question

Je documente quelques méthodes que j'ai écrites en C # et qui traitent de l'analyse des jetons. En raison de contraintes techniques dans d’autres domaines du système, ces jetons doivent se présenter sous la forme d’éléments XML (c.-à-d., <tokenName />). Je voudrais mettre le format de ces jetons dans la déclaration sommaire elle-même.

Cependant, cela génère une erreur: XML mal formé - Un nom a été démarré avec un caractère non valide " ;. Existe-t-il une sorte de séquence de caractère d'échappement que je puisse utiliser pour incorporer XML dans mes commentaires de résumé C #?

Answer 1

Utilisez l'échappement XML standard. Par exemple:

<summary>This takes a &lt;token1&gt; and turns it into a &lt;token2&gt;</summary>

Ce n’est pas très facile de taper ou de lire du code, mais IntelliSense l’écarte correctement et vous voyez ce qu'il y a de mieux, lisible dans l'info-bulle.

Answer 2

Utilisez une section CDATA. Par exemple:

<![CDATA[ <name>Bob</name> ]]>

C’est plus élégant et lisible dans le source que de coder des caractères spéciaux dans les références d’entité lorsque vous avez une pièce XML plus grande.

Si le fichier XML que vous souhaitez incorporer contient des sections CDATA, vous devez utiliser plusieurs sections CDATA comme décrit dans la autre réponse relative au dépassement de capacité ou sur Wikipedia . Ou vous pouvez toujours utiliser des références d'entité telles que décrites dans d'autres réponses ici.

Answer 3

J'utilise des séquences d'échappement, parce que l'info-bulle VisualStudios n'affiche rien qui se trouve à l'intérieur d'une section CDATA.

Answer 4

Il est très tard, mais rencontrez le même problème, utiliser <![CDATA[]]> cachera le commentaire dans Intellisense.

Remplacer à la fois < et > s’est avéré une lourde charge pour moi (lazy :)). J'ai découvert que le simple remplacement de < par <=> était suffisant pour Intellisense, car il rend le code XML invalide et lui permet d'analyser le texte dans votre bloc de résumé.

Voici un exemple:

/// <summary>
/// Parse the queue process response
/// <para>&lt;?xml version="1.0" encoding="utf-16"?>&lt;result success="True">&lt;entity type="resource" operation="update" />&lt;/result></para>
/// <![CDATA[
/// <?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>
/// ]]></summary>
/// <param name="response"></param>
/// <returns></returns>

L'Intellisense affichera ceci:

Parse the queue process response
<?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>