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?

See also Can use "{}" inside cref. A bit more detail on that in If you place it in a cref element, you can instead use { and }. — ToolmakerSteve
– ToolmakerSteve, Commented Mar 22, 2019 at 21:13
Possible duplicate of How do I escape characters in c# comments? — Michael Freidgeim
– Michael Freidgeim, Commented Mar 28, 2019 at 12:08

Palec · Accepted Answer · 2016-12-11 10:55:42Z

41

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.

edited Dec 11, 2016 at 10:55

Palec

13.8k8 gold badges80 silver badges145 bronze badges

answered Mar 3, 2009 at 16:26

Andrew Arnott

82.1k28 gold badges140 silver badges180 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Torge Rosendahl Dec 4, 2024 at 17:04

<a> did not work for me inside the summary section (vs code). However, surrounding the section with <c> worked: <c><a href="mailto:"></a></c> shows as <a href="mailto:"></a>

Palec · Accepted Answer · 2016-12-11 11:08:47Z

31

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.

edited Dec 11, 2016 at 11:08

Palec

13.8k8 gold badges80 silver badges145 bronze badges

answered Mar 3, 2009 at 16:27

Sean

62.8k11 gold badges101 silver badges138 bronze badges

1 Comment

ToolmakerSteve Over a year ago

But see VisualStudio's tooltip doesn't display anything inside a CDATA-section.

Pang · Accepted Answer · 2021-09-29 04:55:06Z

I ran into the same problem. Using <![CDATA[]]> will hide the comment in IntelliSense.

Replacing both < and > was too much work for me (lazy :) ). I found out that just replacing the < with < was enough for IntelliSense because it makes the xml invalid and suitable for 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>

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>

FloWi · Accepted Answer · 2011-12-20 08:59:16Z

7

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

answered Dec 20, 2011 at 8:59

FloWi

1511 silver badge8 bronze badges

Collectives™ on Stack Overflow

Xml string in a C# summary comment

4 Answers 4

1 Comment

1 Comment

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

1 Comment

1 Comment

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related