How to properly escape the content of a `example in Xml documentation?`

Question

Which would be the way to escape VB's and C-Sharp illegal characters like <>& in a <code> tag of .Net Xml documentation?.

In this example below, Intellisense highlights the > character because I need to escape it, it says the code will not be included when generating the documentation because that reason.

''' ------------------------------------------------------------------------
''' <summary>
''' </summary>
''' ------------------------------------------------------------------------
''' <example> This is a code example.
''' <code>
''' 
''' Dim currentPosition As Long = CLng(player.Position.TotalMilliseconds)
''' 
''' If Not ((currentPosition + 5000) >= player.Length) Then
'''    player.Seek(currentPosition + 5000)
''' End If
''' 
''' </code>
''' </example>
''' ------------------------------------------------------------------------
Sub Something
End Sub

Then, how I should escape the code content?.

I have the doubt because the content of <code> tag is treated as literal text, then if I add a CDATA tag to avoid an IntelliSense error what will happens when I'll generate the Chm/Html file with that documentation?, I mean the CDATA markup symbols will be represented as liter text in the code example causing residuous in this way, or what?.

Someone could provide an example to do things right?.

Have you tried using > instead of >? The XML "codes" for <, >, and & are <, >, &. — Martin Soles, Oct 29 '15 at 15:53
@Martin Soles Thanks for comment. That worked for both IntelliSense and the CHM help-file generation. Feel free to publish an answer to mark it as accepted!. — ElektroStudios, Oct 29 '15 at 15:59
Possible duplicate of [How do I escape characters in c# comments?](https://stackoverflow.com/questions/4377372/how-do-i-escape-characters-in-c-sharp-comments) — Michael Freidgeim, Mar 28 '19 at 12:09

score 4 · Accepted Answer · edited May 23 '17 at 12:29

4

You need to use the same type of escaping that you would in a normal XML (or HTML) document (see here for more information).

Replace & with &, < with <, > with >. Another one you might want to watch out for is the quote character. " gets replaced with ".

edited May 23 '17 at 12:29

Community

1
1

answered Oct 29 '15 at 16:06

Martin Soles

534
3
8

6

Ugh. While this does appear to be the solution, it really makes the documentation block itself much less readable when viewing the source code rather than seeing some intellisense tooltip. Consider using generics in C#, where this `MyClass` needs to be written as `MyClass<TType>`. That's awful to read as source code. – HotN Dec 17 '18 at 21:03

How to properly escape the content of a example in Xml documentation?

1 Answers1

How to properly escape the content of a `example in Xml documentation?`