Using Maml in code comments

Jul 15, 2008 at 12:24 AM
Is it possible to embed Maml elements (specifically the 'alert' element) in Xml code comments? I'm after something like this:

/// <summary>
/// Summary description for foo...
/// </summary>
/// <remarks>
/// <alert class="important">
/// <para>Do not use this method. It does nothing!</para>
/// </alert>
/// </remarks>
public static void Foo(Guid id)
{
}
When compiled, I noticed VisualStudio maintained the <alert> tag in the memberlist Xml, but SHFB doesn't emit the alert into the chm. (I'm using the vs2005 style).

Roger

Coordinator
Jul 15, 2008 at 1:44 AM
You can't use MAML elements in XML comments.  However, in this case XML comments do support a <note> tag which is functionally equivalent to the MAML <alert> tag.

<note type="important">
<para>This is important stuff</para>
</note>

For more info on XML comments tags, see the XML Comments Guide.

Eric
Jul 15, 2008 at 2:21 AM
Thanks for the additional info Eric. I hadn't heard of the <note> tag. I was only using the tags mentioned on the MSDN C# comments page at http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

Roger


EWoodruff wrote:
You can't use MAML elements in XML comments.  However, in this case XML comments do support a <note> tag which is functionally equivalent to the MAML <alert> tag.

<note type="important">
<para>This is important stuff</para>
</note>

For more info on XML comments tags, see the XML Comments Guide.

Eric