如何在 Doxygen 评论中包含“<”？答案

【问题标题】：How can I include '<' in Doxygen comments?如何在 Doxygen 评论中包含“<”？
【发布时间】：2012-09-07 17:03:00
【问题描述】：

假设我正在使用与 DOxygen/Visual Studio 兼容的 cmets 记录成员函数，我如何使用小于 '

例如，如果我这样做：

    /// <summary>
    /// Verifies x < y
    /// </summary>
    bool VerifyIsLessThan(float x, float y);

编译器说：

1>c:\MyProject\VerificationLib.h(246) : warning C4635: XML document comment applied to 'VerificationLib.VerifyIsLessThan(System.Single,System.Single)': badly-formed XML: Whitespace is not allowed at this location.

有没有什么办法可以让它在代码库和 Doxygen 生成的文档中仍然可读？

[编辑]

我开始认为这更多地与视觉工作室方面有关，而不是 Doxygen。我们正在使用一种应该对两者都适用的表单。原始问题中提到的警告来自视觉工作室而不是 Doxygen。

再深入一点，看起来逐字不直接supported？

【问题讨论】：

标签： visual-studio-2008 doxygen documentation-generation

【解决方案1】：

只需使用\< 就可以了。 http://www.doxygen.nl/manual/commands.html#cmdlt

【讨论】：

有什么办法可以做到不降低可读性吗？在这个简单的例子中，它并不算太糟糕，但是如果（比如说）你把它作为等式的一部分，斜线看起来就像分号......
\ 的替代方法是使用 @ 代替。这看起来并没有好多少，但不能与那么容易的分隔符号混淆。
有formulas in doxygen。我从未使用过它们，但看起来它仍然需要转义 <.>
我认为你对 DOxygen 的公式是正确的，但我找不到任何方法让 MS XML 文档理解一个“` or a 转义它@` 符号。唯一接近的是&lt;，但这在代码库中看起来很糟糕。

【解决方案2】：

您可以使用code 或verbatim。

【讨论】：

...但这必须是一个完整的块，而不是与<summary> </summary> 块内联，对吗？即/// <summary>Make sure x is <verbatim><</verbatim> y </summary> 不起作用...

【解决方案3】：

我能找到的唯一一个允许将 &lt; 字符内联到摘要中的东西似乎是 &lt;，但即使智能感知和 doxygen 看起来不错，它在实际代码库中仍然看起来很丑......

【讨论】：

【解决方案4】：

您也可以将 cmets 放入 CDATA 块中，如下所示：

<![CDATA[ Verifies x < y ]]>

我不知道你是否真的认为这更容易阅读，但它有助于避免 Jon Cage 指出的问题，其中 \ 可能被误解为除法符号或其他任何东西。

附加信息：

What does <![CDATA[]]> in XML mean?

http://forums.asp.net/t/1007641.aspx/1

【讨论】：