XML Comments - MSDN Documentation "Note" section -- how do you duplicate this?

Question

Basically, in the MSDN online help I often run into a "NOTE" section, but cannot for the life of me figure out how to get that same output. Apparently there is no <note> tag. Does anyone know how to get this working?

IDictionary(TKey, TValue) — In this example, if you go down to the remarks section you'll see what I'm talking about.

I'm using Sandcastle Help File Builder.

Answer 1

To expand on cubrr's comment on Bobby's answer there is actually now some reasonably extensive documentation on the Note element in Sandcastle.

There are four categories of note you can add to any other default xml element such as the remark or summary elements. These are General, Cautionary, Security or Language. The main difference between them seems to be the type of icon they give the note and the title that the note has next to the icon. You can see the full list of all these note types here.

The following code generated the below result for me:

/// <remarks>
/// <note type="note">
/// This is a note in a remark. It is a General note.
/// </note>
/// <note type="tip">
/// This is a tip note in a remark. It is a General note.
/// </note>
/// <note type="implement">
/// This is a implement note in a remark. It is a General note.
/// </note>
/// <note type="caller">
/// This is a caller note in a remark. It is a General note.
/// </note>
/// <note type="inherit">
/// This is a inherit note in a remark. It is a General note.
/// </note>
/// <note type="caution">
/// This is a caution note in a remark. It is a Cautionary note.
/// </note>
/// <note type="important">
/// This is a important note in a remark. It is a Cautionary note.
/// </note>
/// <note type="security">
/// This is a security note in a remark. It is a Security note.
/// </note>
/// <note type="cs">
/// This is a cs note in a remark. It is a Language note.
/// </note>
/// </remarks>

Result: Generated Help File

Answer 2

Actually both Sandcastle and Sandcastle Help File Builder support a <note> element, though it is extremely well-hidden! :-) It is only documented in two places that I am aware of:

1. The XML Documentation Comments Guide reference from Dyncity... which is apparently no longer available on the web--the link used to be http://www.dynicity.com/downloads/default.aspx.
2. A wallchart accompanying my article on Simple-Talk.com entitled Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code. Note that there is a link in the article to get to the wallchart, but it is at the very bottom of the article so I have given links for both here. (I have a reference to Dyncity's guide in my article as well; I will communicate with the editorial staff to see if they want to host a local copy of the now-orphaned Dyncity guide and post an update here if they do.)

Here is about all the documentation there is for the <note> element. (This is from my wallchart; the Dyncity guide says essentially the same thing but a lot less concisely.)

That inadequate documentation is regrettably all that I have found about <note>. So I ran a quick trial, embedding each note type within a Remarks section. Here is what it produced:

---

That is, with type="caution" you get the caution icon and label while the other two type attribute values produced the same note icon and label in my particular example. I suspect there may be other facets of its use deeply buried in the underbrush.

Answer 3

There is very little documentation on Sandcastle, but the note output is potentially from Sandcastle and not C#'s native XML comment tags.

You can try using the following code where you want to put a note section and see what Sandcastle outputs (this used to be supported not sure if it has changed):

<alert class="note">This is a 'alert class=note'</alert>

See: Microsoft Assistance Markup Language Longhorn Help for more information.