我在这里看到了涉及Microsoft's XML documentation tags 的各种问题,但我在添加一些示例代码时遇到了麻烦:
/// <summary>Return the oldest acceptable timestamp for a data packet.</summary>
/// <example>
/// if( GetOldestValidResultTime() < lastResultTime )
/// {
/// Console::WriteLine("Results are too old");
/// }
/// </example>
/// <returns>The timestamp (the Milliseconds field from a raw result) of the oldest acceptable data item given the timestamp in the latest result in the internal buffer.</returns>
long GetOldestValidResultTime();
这给了我:
DataProcessor.h(154) : warning C4635: XML document comment applied to 'MyApp.DataProcessor.GetOldestValidResultTime': badly-formed XML: Only one top level element is allowed in an XML document.
<
如果您直接阅读源代码而不是 DOxygen 输出(例如),那么除了使用使示例更难遵循之外,还有什么方法可以解决这个问题?..或者<
代码是这里唯一的选择吗?
[编辑]我已经尝试过建议的 CDATA 块,但它似乎只适用于单行:
/// <example><![CDATA[ test < 5; ]]></example>
/// <example>
/// <![CDATA[ test < 5; ]]>
/// </example>
..但不是多行注释,这实际上可能是一个可读的例子:
/// <example><![CDATA[
/// test < 5;
/// ]]> </example>
[Edit2]尝试了 pierrre 的建议,即从可以预见的失败的最后两个语句前面删除 \\'s:
/// <example><![CDATA[
test < 5;
]]> </example>
给出:
error C2143: syntax error : missing ';' before '<'