Important
The type attribute value is case-sensitive. Unrecognized values will default to the "note" style.
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" [title="Optional title override"]>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.
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 |
To Do | todo |
An optional title attribute can be used to provide a user-defined title that it will override the default title.
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 parentheses when calling this method in C#.
/// </note>
///
/// <note type="VB">
/// Parentheses are not required when calling this method in Visual Basic.
/// </note>
///
/// <note type="C++">
/// Use parentheses when calling this method in C++.
/// </note>
///
/// <note type="J#">
/// Use parentheses when calling this method in J#.
/// </note>
///
/// <note type="todo">
/// This could contain a To Do list.
/// </note>
///
/// <note type="todo" title="Project Road Map">
/// This note contains a custom title.
/// </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()
{
}