note

Sandcastle XML Comments

Sandcastle XML Comments Guide note

This element is used to create a note-like section within a topic to draw attention to some important information.

Syntax

This inline block element can be used within any other element.

<note type="noteType">note content</note>

The type attribute defines the note type. The noteType value should be one of the values shown below. If omitted, a default note type of "note" is assumed. The note content can be any valid inline or block XML comments similar to a remarks element.

Important note Important

The type attribute value is case-sensitive. Unrecognized values will default to the "note" style.

The type attribute can be any of the following values which fall into four different categories that use different icons to the left of the note title. The title will generally be the note type name or an expanded form of it.

Category

Type Value

General note

note, tip, implement, caller, inherit

Cautionary

caution, warning, important

Security

security, security note

Language note

cs, CSharp, c#, C#, visual c# note, cpp, CPP, c++, C++, visual c++ note, vb, VB, VisualBasic, visual basic note, JSharp, j#, J#, visual j# note

Note Note

This is a custom XML comments element implemented by Sandcastle. It will not appear in the list of valid elements for XML comments IntelliSense.

Examples
/// <summary>
/// This shows the result of the various <c>note</c> types.
/// </summary>
/// <remarks>
/// <para>These are various examples of the different note types.</para>
/// 
/// <note>
/// This example demonstrates the handling of a <c>note</c> element with no
/// defined type.  It defaults to the "note" style.
/// </note>
/// 
/// <note type="tip">
/// Always document your code to help others understand how it is used.
/// </note>
/// 
/// <note type="implement">
/// Override this method in a derived class to do something useful
/// </note>
/// 
/// <note type="caller">
/// Calling this implementation will have no effect at all
/// </note>
/// 
/// <note type="inherit">
/// Types inheriting this base method will have no use for it as it does nothing
/// </note>
/// 
/// <note type="caution">
/// Use of this method is not recommended.
/// </note>
/// 
/// <note type="warning">
/// XML is case-sensitive so the note type must be entered as shown in order for
/// it to be interpreted correctly.
/// </note>
/// 
/// <note type="important">
/// Calling this method excessively will only slow down your application.
/// </note>
/// 
/// <note type="security">
/// It is always safe to call this method.
/// </note>
/// 
/// <note type="security note">
/// This method requires no special privileges
/// </note>
/// 
/// <note type="C#">
/// Use parenthesis when calling this method in C#.
/// </note>
/// 
/// <note type="VB">
/// Parenthesis are not required when calling this method in Visual Basic.
/// </note>
/// 
/// <note type="C++">
/// Use parenthesis when calling this method in C++.
/// </note>
/// 
/// <note type="J#">
/// Use parenthesis when calling this method in J#.
/// </note>
/// 
/// <para>See the <conceptualLink target="4302a60f-e4f4-4b8d-a451-5f453c4ebd46" />
/// topic for a full list of all possible note types.</para>
/// </remarks>
public virtual void VariousNoteExamples()
{
}
See Also

Reference

Other Resources