Putting comments in XML that is present in my C# XML comment blocks

Question

I am using a code example block in an XML comment as a simple way to give the user an idea of what the XML looks like. This is a very rough solution and the user will eventually be provided with XML Schema for the xml string. However, for now I'm going to just provide this information in my doxygen-based documentation.

For example, I've got something like this:

/// <example>
/// <code>
///   <!-- xml will go below this comment, but I can't display the comment! -->
/// </code>
/// </example>

When I look at my documentation, any line that has a comment just appears as a blank line.

I've tried escaping with < and >, and have also tried using <CDATA[<!-- comment -->]]>, without success. The escape sequences are displayed as-is, and CDATA appears as-is, except that the character data is not shown.

What did I miss here? :)

EDIT -- I need to clarify that this is not an issue with Intellisense rendering the information. I would like the XML comments to display properly when rendered by Doxygen into a CHM (via HTML Help Workshop).

Answer 1

I'm not sure where your XML source is appearing, is it in the documentation of a function or class? If so, try wrapping the XML in verbatim and \endverbatim tags. For the following example

/** A test class with some XML in the documentation.

 \verbatim
 <example>
 <code>
   <!-- xml will go below this comment, but I can't display the comment! -->
 </code>
 </example>
 \endverbatim
*/
class Test
    ...

I get the doxygen output:

Answer 2

When you tried escaping with < and >, did you use this syntax?

/// <example>
/// <code>
///   &lt;!-- xml will go below this comment, but I can't display the comment! --&gt;
/// </code>
/// </example>

It works in IntelliSense, and I don’t see any reason why it shouldn’t work elsewhere.

Edit: Could you please try the following version?

/// <example>
/// <pre lang='xml'> 
///   &lt;!-- xml will go below this comment, but I can't display the comment! --&gt;
/// </pre> 
/// </example>