views:

88

answers:

1

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 &lt; which makes examples much harder to follow if you're reading the source directly as opposed to DOxygen output (for example)? ..or is the &lt; 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 '<'
+4  A: 

Use a CDATA block.

Pierre 303
Tried this, but it only appears to work for a single line? See the edit I just made.
Jon Cage
In a CDATA block you can add lot of things and is not single lined. Try to remove /// in front of test <5 and /// in front of ]]>
Pierre 303
Also copy/paste the error you get if it doesn't work.
Pierre 303
Failed again - see edit2
Jon Cage
Look at this: http://www.shrinkrays.net/code-snippets/csharp/-net-xml-comment-cheat-sheet.aspx. Removing the /// is not necessary
Pierre 303
I just tried their sample and it doesn't seem to work for me.
Jon Cage