Ugrás a fő tartalomra

Xml string in a C# summary comment

up vote30down votefavorite
4
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?
 
shareimprove this question

4 Answers

up vote38down voteaccepted
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.
shareimprove this answer
up vote25down vote
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.
shareimprove this answer
up vote4down vote
I use escape-sequences, because VisualStudios tooltip doesn't display anything that's inside a CDATA-section.
shareimprove this answer
up vote2down vote
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 &lt; 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>
shareimprove this answer
Címkék:

Megjegyzések

Megjegyzés küldése

Népszerű bejegyzések ezen a blogon

SW Documentation: Requirements

Requirements Nonfunctional Requirements Q&A FEBRUARY 17, 2010  ~  ANDREW STELLMAN ~  3 COMMENTS Non-functional requirements Q&A: We answer questions from readers about using  nonfunctional requirements  on a real software project, and how to use them on a real software project. Non-functional requirements: Planning out how well your software will work A couple of months ago I wrote a post called  Using nonfunctional requirements to build better software . It’s basically a step-by-step guide for creating an easy, practical technique to use nonfunctional requirements on a real software project, treating them in a way that’s similar to how a lot of Agile teams treat user stories, scenarios and other functional requirements: by sticking them on index cards and using them to do some lightweight planning. Since then, I’ve gotten a lot of questions about nonfunctional requirements (or, as some people call them, non functional requirements...
Megjegyzés küldése
További információk

Privacy Notice for Visitors to Our Users’ Sites

Privacy Notice for Visitors to Our Users’ Sites Sections Who’s Who and What This Privacy Notice Covers Information We Collect About Visitors to Our Users’ Sites Information a Visitor Provides to a Site Information We Automatically Collect from the Site Other Information Provided by Our Users How We Use Visitor Information How We Share Visitor Information Other Tools Other Resources Hi there! This Privacy Notice explains how we, at Automattic, process information about the visitors of our users’ websites in connection with the services we provide through WordPress.com, Jetpack (including WooCommerce Services), IntenseDebate, Polldaddy.com, and Akismet. Read on! Who’s Who and What This Privacy Notice Covers Let’s talk first about who we are at Automattic, what we do, and what this Privacy Notice covers. We are the folks behind a variety of products and services designed to allow anyone–from bloggers, to small business owners, and enterprises–to create, publ...
Megjegyzés küldése
További információk

THE RIGHT WAY TO WRITE A SINGLETON

THE RIGHT WAY TO WRITE A SINGLETON July 17, 2015 by   Hector Matos Even though I've written about the woes of managing state in my previous post, sometimes there's just no way we can avoid it. One example of managing state is something we're all quite acquainted with - The Singleton. The problem we find in Swift is that there are SEVERAL ways of implementing them. But which way is the right way? In this post I'm going to show you the history of the singleton and then show you the right way to implement the singleton in Swift. If you want to see the right way to implement the singleton pattern in Swift along with proof of it's "right-ness", you can scroll to the bottom of the post and see it there. :) A TRIP DOWN MEMORY LANE Swift is a natural evolution of Objective-C. In Objective-C, this is how we implemented the singleton: @interface Kraken : NSObject @end @implementation Kraken + ( instancetype ) sharedInstance { ...
Megjegyzés küldése
További információk