How do I escape characters in C# comments?

I realized today that I don't know how to escape characters in comments for C#. I want to document a generic C# class, but I cannot write a proper example since I don't know how to escape the < and > characters. Do I have to use < and >? I don't like if that is the case since I want to make it easy to read the comment in t开发者_JS百科he actual document so I don't have to generate some kind of code document to be able to read the example code.

If you need to escape characters in XML comments, you need to use the character entities, so < would need to be escaped as <, as in your question.

The alternative to escaping is using CDATA sections, to the same effect.

As you noted, this would produce good looking documentation, but a horrible comment to read...

In plain C# comments you can use any character (except */ if you started the comment with /*, or the newline character if you started the comment with //). If you are using XML comments then you can use a CDATA section to include '<' and '>' characters.

See this MSDN blog article for more information on XML comments in C#.

For example

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

You said "I want to make it easy to read the comment in the actual document". I agree.

Developers spend most of their lives in the code, not perusing auto-generated docs. Those are great for thirdparty libraries like charting, but not for in-house development where we work with all of the code. I'm sort of shocked that MSFT hasn't come up with a solution that supports developers better here. We have regions that dynamically expand/collapse code...why can't we have an in-place comment rendering toggle (between raw text and processed XML comment or between raw text and processed HTML comment)?. Seems like I should have some elementary HTML capabilities in my method/class prologue comments (red text, italics, etc). Surely an IDE could work a little HTML processing magic to liven up inline comments.

My hack-of-a-solution solution: I change '<' to "{" and '>" to "}". That seems to cover me for the typical example usage style comment, including your specific example. Imperfect, but pragmatic given the readability issue (and problems with IDE comment coloring that ensue when using '<')

C# XML comments are written in XML, so you would use normal XML escaping.

For example...

<summary>Here is an escaped &lt;token&gt;</summary>

I've found a livable solution to this problem is simply including two examples: one difficult-to-read version in the XML comments w/ escape characters, and another readable version using conventional // comments.

Simple, but effective.

Better than using {...} is using ≤...≥ (less than or equals sign, greater than or equals sign, U2264 and U2265 in Unicode). Looks like underlined angle brackets but still definitely angle brackets! And only adds a couple of bytes to your code file.

Even better try U2280 and U2281 - just copy and paste from List of Unicode characters (mathematical operators section).

I like @Mick Bruno's idea of using similar looking characters to keep it legible in the code. Single guillemets work pretty well:

List‹int›

The Windows keyboard shortcuts are:

• Alt+0139
• Alt+0155

(where the numbers are typed on the keypad)