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

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.