MAML/XML Comments

This topic covers common questions and issues related to Microsoft Assistance Markup Language (MAML) and XML comments.

• How can I learn about Microsoft Assistance Markup Language (MAML) and how to use it?
• How can I learn about XML comments elements and how to use them?
• How do I specify a generic such as IEnumerable<T> in a cref target and/or XML comments?
• Can I use HTML markup in my XML comments?
• Can I use HTML markup in my MAML topics?
• How can I embed an image in a namespace, type, or member's help topic?
• How can I create a link to a namespace element's help topic from a conceptual content topic?
• How can I create a link to an conceptual content/additional content page from a namespace, type, or member help topic?
• How can I document WPF attached events and attached properties?

See the Sandcastle MAML Guide for information on MAML and how to use it. See the topics in the Conceptual Content section of this help file for information on adding conceptual content to help file builder projects.

See the Sandcastle XML Comments Guide for information on XML comments and how to use them.

Use curly braces in cref targets and HTML entities (&lt; and &gt;) in the general XML comments. For example:

/// <remarks>
/// <para>See <see cref="IEnumerable{T}"/> for more information.</para>
/// <para>Another reference to <c>IEnumerable&lt;T&gt;</c> that is not a link.</para>
/// </remarks>

Yes, you can use HTML markup in your XML comments to add additional formatting. You can also use the img element to embed an image in a namespace element's XML comments. Since the comments are XML, all HTML elements must be specified with a closing element or as self-closing (i.e <p>This is a paragraph</p> or <p/>New paragraph).

Not directly. However, you can wrap a block of HTML in a markup element so that it passes through as-is. However, this circumvents the purpose of MAML which is to separate the topic's content from the physical markup. You are much better off using an equivalent MAML element to format the content if one exists. See the markup element topic in the Sandcastle MAML Guide for more information.

Embedding an image in an element's help topic is a two step process. First, you must add the image to the help file builder project as a content item (add it using the Project Explorer window and set the BuildAction to Content). The second step is to edit the member's XML comments (summary, remarks, etc.) to add the img tag. To embed an image in the project summary or namespace comments, add the image tag to the help file builder's ProjectSummary property text or to a namespace's comments using the NamespaceSummaries project property.

Below are two examples of embedding an image in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the image file. The first example assumes that the image is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the image is copied to an .\Images folder. In that case, you must also specify the folder name. As noted above, the image tag must be self-closing to conform to the XML specification.

/// <summary>
/// A class member.
/// </summary>
/// <remarks>An image: <img src="../Process.gif"/></remarks>
public void TestMethod()
{
    // ... Method implementation ...
}

/// <summary>
/// A useful class.
/// </summary>
/// <remarks>
/// UML Diagram: <img src="../Images/TestClassUML.gif" alt="UML Diagram" />
/// </remarks>
public TestClass
{
    // ... Class implementation ...
}

Use the Entity References Window to add a link to the topic. Select the Code Entities option, search for the member, drag it's ID from the results pane, and drop it in the topic where you want it.

For conceptual content (MAML) topics, use a conceptualLink element to reference the topic. The XML Comments Guide contains more information and examples. The Entity References Window can be used to add a link. Set the Type to "Table of Contents", change the Insert as option to "XML comments conceptualLink", drag the topic from the table of contents to the XML comments, and drop it where you want it.

For HTML pages, edit the member's XML comments (summary, remarks, etc) to add an anchor (<a>) tag that points to the additional content page. To add a link in the Project Summary or Namespace comments, add the anchor tag to the help file builder's Project Summary notes or namespace comments. Below are two examples of adding a link in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the additional content file. The first example assumes that the file is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the file is copied to a .\Tutorials folder. In that case, you must also specify the folder name.

/// <summary>
/// A class member.
/// </summary>
/// <remarks>Class usage tutorial:
/// <a href="../SomeClassTutorial.html">SomeClass Tutorial</a>
/// </remarks>
public void TestMethod()
{
    // ... Method implementation ...
}

/// <summary>
/// A useful class.  For more information see the
/// <a href="../Tutorials/SomeClass.html">tutorial</a>.
/// </summary>
public TestClass
{
    // ... Class implementation ...
}

See the XML comments guide, specifically the topics on the AttachedEventComments and AttachedPropertyComments elements. Examples are provided.

Other Resources