Cadena de Xml en un comentario de resumen de C#

Question

Estoy documentando algunos métodos que escribí en C# que se ocupan de los tokens de análisis. Debido a algunas restricciones técnicas en otras áreas del sistema, estos tokens deben tomar la forma de elementos XML (es decir, <tokenName />). Me gustaría poner el formato de esos tokens en la declaración resumen en sí.

Sin embargo, esto genera un error:. XML mal formado - Un nombre se inició con un carácter no válido"¿Hay alguna especie de secuencia de escape que puede utilizar para incrustar XML en mis C Comentarios Resumen #

Answer 1

? utilizar XML estándar de escape Por ejemplo:.

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

no es super-fácil de escribir o leer como código, pero IntelliSense caracteres de escape propiamente dicho y se ve que es correcto, legible en la descripción

Answer 2

uso a. Sección CDATA. Por ejemplo:

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

Esta fuente es más elegante y legible que la codificación de caracteres especiales en referencias de entidad cuando se tiene una pieza XML más grande.

Si el XML que desea incrustar tiene secciones CDATA, debe usar varias secciones CDATA como se describe en another answer on Stack Overflow o en Wikipedia. O siempre puede usar referencias de entidades simples como se describe en otras respuestas aquí.

Answer 3

Uso escape-sequences, porque VisualStudios tooltip no muestra nada que esté dentro de una sección CDATA.

Answer 4

Es muy tarde, pero se encontró con el mismo problema, usando <![CDATA[]]> se ocultará el comentario en Intellisense.

Reemplazar < y > fue mucho para mí (flojo :)). Descubrí que reemplazar el < con < era suficiente para el Intellisense porque hace que el xml no sea válido y adecuado para que el Intellisense lo analice como texto en el bloque de resumen.

Aquí se muestra un ejemplo:

/// <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> 

El Intellisense mostrará esto:

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