0

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 &lt; and &gt;, 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).

Dave
  • 14,618
  • 13
  • 91
  • 145

2 Answers2

1

When you tried escaping with &lt; and &gt;, 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.

IntelliSense screenshot

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>
Douglas
  • 53,759
  • 13
  • 140
  • 188
  • Yes, that's exactly what I did. Perhaps my issue here is my assumption that Doxygen / HTML Help will render the comments properly! Thanks for pointing that out. – Dave May 14 '12 at 18:41
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:

enter image description here

albert
  • 8,285
  • 3
  • 19
  • 32
Chris
  • 44,602
  • 16
  • 137
  • 156
  • Thanks, Chris! The problem with your solution is that you're also displaying the and tags, where I just want the XML comment inside of the tag. That said, I can use your solution if I just use `\verbatim` as a substitute for the tag! Works well enough for me! – Dave May 15 '12 at 12:26
  • Great. You can also use [`\verbinclude`](http://www.stack.nl/~dimitri/doxygen/commands.html#cmdverbinclude) or `\htmlinclude` if you want to include XML from other files, i.e. if you want to have example XML files in a sub directory, rather than embedded in your source code. – Chris May 15 '12 at 12:31
  • 1
    Oh that's even better. :) Thanks for the suggestions! – Dave May 15 '12 at 12:52