Usage Notes

• XML comments support all of the common HTML tags such as a (anchor), b (bold), img (image), p (paragraph), etc. As such, you can use HTML markup to add additional formatting to your XML comments if necessary.

  Caution

  Not all help output formats support HTML elements in XML comments or may use a different URL format from other help formats. For example, MS Help Viewer's URL format differs from the other help formats which may result in broken links if literal HTML anchor or image links are used. As such, try to use XML comments elements whenever possible. For example, to link to API topics, use see elements and for conceptual topics, use conceptualLink.

• All XML and HTML within XML comments must be well formed. That means that all elements must have a corresponding closing element or must be self-closing, special characters such as "<" and ">" must be encoded appropriately (i.e. &lt; and &gt;), entities not recognized by the XML parser must be encoded in their numeric form (i.e. &#160; rather than &nbsp; for a non-breaking space).

• For larger blocks of XML that you want to insert literally such as code examples, you can use the <![CDATA[ ]]> option to place them in the element. See the code element for an example.

• When referencing a generic type or a member with generic parameters as the target of an element attribute such as the cref attribute on a see element, use curly braces rather than angle brackets on the generic type parameters. For example:

  Copy

  /// <summary>
  /// This class is derived from <see cref="List{T}" />
  /// </summary>
  /// <typeparam name="T">The element type of the list</typeparam>
  /// <seealso cref="CustomDictionary{TKey, TValue}" />
  public class CustomList<T> : List<T>
  {
  }

• Namespace comments cannot be attached directly to a namespace code element. Instead, you must use an alternate means to specify namespace comments. See the Namespace Comments topic for more information.

Other Resources