I've seen various questions here on SO involving Microsoft's XML documentation tags, but I'm having trouble adding some example code:
/// <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();
This gives me:
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.
Is there any way around this other than using <
which makes examples much harder to follow if you're reading the source directly as opposed to DOxygen output (for example)? ..or is the <
code the only option here?
[Edit] I've tried the suggested CDATA block but it only appears to work for single-lines:
/// <example><![CDATA[ test < 5; ]]></example>
/// <example>
/// <![CDATA[ test < 5; ]]>
/// </example>
..but not multi-line comments which might actually make for a readable example:
/// <example><![CDATA[
/// test < 5;
/// ]]> </example>
[Edit2] Tried pierrre's suggestion of removing the \\'s from in front of the last two statements which predictably failed:
/// <example><![CDATA[
test < 5;
]]> </example>
gives:
error C2143: syntax error : missing ';' before '<'