Xml string in a C# summary comment

Question

I'm documenting a few methods I wrote in C# that deal with parsing tokens. Due to some technical restraints in other areas of the system, these tokens need to take the form of XML elements (i.e., <tokenName />). I'd like to put the format of those tokens in the summary statement itself.

However, this throws an error: Badly formed XML -- A name was started with an invalid character". Is there any sort of escape character sequence I can use to embed XML in my C# summary comments?

Answer 1

Use standard XML escaping. For example:

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

It's not super-easy to type or read as code, but IntelliSense properly unescapes this and you see the right, readable thing in the tooltip.

Answer 2

Use a CDATA section. For example:

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

This is more elegant and readable in source than encoding special characters in entity references when you have a larger XML piece.

If the XML you want to embed itself contains CDATA sections, you need to use multiple CDATA sections as described in another answer on Stack Overflow or on Wikipedia. Or you can always use plain entity references as described in other answers here.

Answer 3

I use escape-sequences, because VisualStudios tooltip doesn't display anything that's inside a CDATA-section.

Answer 4

It's very late, but ran into the same problem, using <![CDATA[]]> will hide the comment in Intellisense.

Replacing both < and > was to much work for me (lazy :) ). I found out that just replacing the < with < was enough for the Intellisense because it makes the xml invalid and suitable for the Intellisense to parse as text in your summary block.

Here is an example:

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

The Intellisense will show this:

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