将注释放入我的 C# XML 注释块中存在的 XML 中答案

【问题标题】：Putting comments in XML that is present in my C# XML comment blocks将注释放入我的 C# XML 注释块中存在的 XML 中
【发布时间】：2012-05-22 06:29:35
【问题描述】：

我在 XML 注释中使用代码示例块作为一种简单的方式让用户了解 XML 的外观。这是一个非常粗略的解决方案，最终将为用户提供 xml 字符串的 XML Schema。但是，现在我将只在基于 doxygen 的文档中提供这些信息。

例如，我有这样的东西：

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

当我查看我的文档时，任何有注释的行都会显示为空白行。

我尝试使用&lt; 和&gt; 进行转义，也尝试使用<CDATA[]]>，但均未成功。转义序列按原样显示，CDATA 按原样显示，只是字符数据未显示。

我在这里错过了什么？ :)

编辑——我需要澄清这不是 Intellisense 呈现信息的问题。我希望 XML cmets 在 Doxygen 呈现到 CHM 时正确显示（通过 HTML Help Workshop）。

【问题讨论】：

标签： c# xml doxygen xml-comments html-help-workshop

【解决方案1】：

我不确定您的 XML 源代码出现在哪里，它是在函数或类的文档中吗？如果是这样，请尝试将 XML 包装在 verbatim 和 \endverbatim 标记中。对于以下示例

/** 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
    ...

我得到了 doxygen 输出：

【讨论】：

谢谢，克里斯！您的解决方案的问题是您还显示了和 标记，我只希望标记内的 XML 注释。也就是说，如果我只使用 \verbatim 作为标记的替代品，我可以使用您的解决方案！对我来说效果很好！
太棒了。如果您想从其他文件中包含 XML，也可以使用 \verbinclude 或 \htmlinclude，即如果您想在子目录中包含示例 XML 文件，而不是嵌入到源代码中。
哦，那就更好了。 :) 感谢您的建议！

【解决方案2】：

当您尝试使用&lt; 和&gt; 进行转义时，您是否使用了这种语法？

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

它可以在 IntelliSense 中工作，我看不出它为什么不能在其他地方工作。

编辑：你能试试下面的版本吗？

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

【讨论】：

是的，这正是我所做的。也许我的问题是我假设 Doxygen / HTML Help 将正确呈现 cmets！感谢您指出这一点。