5

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.

3 Answers 3

6

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.)

Syntax of note element

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:


Sample Sandcastle note output

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.

3
  • There definitely needs to be better XML Commenting / Sandcastle documentation. The most annoying thing is I can not get my generated site to look identical to the MSDN site.
    – myermian
    Sep 14, 2011 at 15:09
  • @m-y: As to your first remark: that's why I wrote the article I referenced above--it goes a long way to filling in the gaps :-) As to the second: I share your pain! Sep 14, 2011 at 16:58
  • For future readers: Sandcastle has an XML comments guide available: at ewoodruff.us/xmlcommentsguide
    – cbr
    Jan 11, 2015 at 19:19
2

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

1

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.

1
  • The Sandcastle MAML Guide documents <alert class="note">...</alert>, but the Sandcastle XML Comments Guide documents <note type="note">...</note>. At this point I'm assuming the syntax is treated equivalently by the toolchain. Aug 9, 2013 at 12:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.