The <c> tag indicates that the enclosed text should be formatted as code, rather than normal text. It's used for code that is included in a normal text block. The structure of <c> is simple, with any text appearing between the opening and closing tags being marked for formatting in the code style.

<c>code-formatted text</c>

The following example shows how <c> might be used in the description of a property:

If the amount of text in the documentation you need to format as code is more than just a phrase within a normal text block, you can use the <code> tag instead of <c>. This tag marks everything within it as code, but it's a block-level tag, rather than a character-level tag. The syntax of this tag is a simple opening and closing tag with the text to be formatted inside, as shown here:

<code>
Code-formatted text
Code-formatted text
</code>

The <code> tag can be embedded inside any other XML comment tag. The following code shows an example of how it could be used in the summary section of a property definition:

A common requirement for internal documentation is to provide an example of how a particular procedure or member can be used. The <example> tags indicate that the enclosed block should be treated as a discrete section of the documentation, dealing with a sample for the associated member. Effectively, this doesn't do anything more than help organize the documentation, but used in conjunction with an appropriately designed XML style sheet or processing instructions, the example can be formatted properly.

The other XML comment tags, such as <c> and <code>, can be included in the text inside the <example> tags to give you a comprehensively documented sample. The syntax of this block-level tag is simple:

<example>
Any sample text goes here.
</example>

Using the example from the previous discussion, the following code moves the <code> formatted text out of the <summary> section into an <example> section:

The <exception> tag is used to define any exceptions that could be thrown from within the member associated with the current block of XML documentation. Each exception that can be thrown should be defined with its own <exception> block, with an attribute of cref identifying the fully qualified type name of an exception that could be thrown. Note that the Visual Studio 2010 XML comment processor checks the syntax of the exception block to enforce the inclusion of this attribute. It also ensures that you don't have multiple <exception> blocks with the same attribute value. The full syntax is as follows:

<exception cref="exceptionName">
Exception description.
</exception>

Extending the examples from the previous tag discussions, the following code adds two exception definitions to the XML comments associated with the UserId property: System.TimeoutException, and System.UnauthorizedAccessException.

You'll often have documentation that needs to be shared across multiple projects. In other situations, one person may be responsible for the documentation while others are doing the coding. Either way, the <include> tag will prove useful. The <include> tag enables you to refer to comments in a separate XML file so they are brought inline with the rest of your documentation. Using this method, you can move the actual documentation out of the code, which can be handy when the comments are extensive.

The syntax of <include> requires that you specify which part of the external file is to be used in the current context. The path attribute is used to identify the path to the XML node, and uses standard XPath terminology:

<include file="filename" path="XPathQuery" />

The external XML file containing the additional documentation must have a path that can be navigated with the attribute you specify, with the end node containing an attribute of name to uniquely identify the specific section of the XML document to be included.

You can include files in either VB or C# using the same tag. The following code takes the samples used in the <exception> tag discussion and moves the documentation to an external file:

The external file's contents would be populated with the following XML document structure to synchronize it with what the <include> tag processing expects to find:

<MyDoc>
  <Properties name="UserId">
    <summary>
      The <c>sender</c> object is used to identify who invoked the procedure.
    </summary>
    <summary>
      The <c>UserId</c> property is used in conjunction with other properties
      to setup a user properly. Remember to set the <c>Password</c> field too.
    </summary>
    <exception cref="System.TimeoutException">
      Thrown when the code cannot determine if the user is valid within a
      reasonable amount of time.
    </exception>
    <exception cref="System.UnauthorizedAccessException">
      Thrown when the user identifier is not valid within the current context.
    </exception>
    <example>
      <code>
        myUser.UserId = "daveg"
        myUser.Password = "xg4*Wv"
      </code>
    </example>
  </Procedures>
</MyDoc>

Some documentation requires lists of various descriptions, and with the <list> tag you can generate numbered and unnumbered lists along with two-column tables. All three take two parameters for each entry in the list — a term and a description — represented by individual XML tags, but they instruct the processor to generate the documentation in different ways.

To create a list in the documentation, use the following syntax, where type can be one of the following values — bullet, numbered, or table:

<list type="type">
   <listheader>
      <term>termName</term>
      <description>description</description>
   </listheader>
   <item>
      <term>myTerm</term>
      <description>myDescription</description>
   </item>
</list>

The <listheader> block is optional, and is usually used for table-formatted lists or definition lists. For definition lists, the <term> tag must be included, but for bullet lists, numbered lists, or tables the <term> tag can be omitted.

The XML for each type of list can be formatted differently using an XML style sheet. An example of how to use the <list> tag appears in the following code. Note how the sample has omitted the listheader tag, because it was unnecessary for the bullet list:

Without using the various internal block-level XML comments such as <list> and <code>, the text you add to the main <summary>, <remarks>, and <returns> sections all just runs together. To break it up into readable chunks, you can use the <para> tag, which simply indicates that the text enclosed should be treated as a discrete paragraph. The syntax is simple:

<para>This text will appear in a separate paragraph.</para>

To explain the purpose of any parameters in a function declaration, you can use the <param> tag. This tag will be processed by the Visual Studio XML comment processor with each instance requiring a name attribute that has a value equal to the name of one of the properties. Enclosed between the opening and closing <param> tag is the description of the parameter:

<param name="parameterName">Definition of parameter.</param>

The XML processor will not allow you to create multiple <param> tags for the one parameter, or tags for parameters that don't exist, producing warnings that are added to the Error List in Visual Studio if you try. The following example shows how the <param> tag is used to describe two parameters of a function:

If you are referring to the parameters of the method definition elsewhere in the documentation other than the <param> tag, you can use the <paramref> tag to format the value, or even link to the parameter information depending on how you code the XML transformation. The compiler does not require that the name of the parameter exist, but you must specify the text to be used in the name attribute, as the following syntax shows:

<paramref name="parameterName" />

Normally, <paramref> tags are used when you are referring to parameters in the larger sections of documentation such as the <summary> or <remarks> tags, as the following example demonstrates:

To describe the code access security permission set required by a particular method, use the <permission> tag. This tag requires a cref attribute to refer to a specific permission type:

<permission cref="permissionName">
   description goes here
</permission>

If the function requires more than one permission, use multiple <permission> blocks, as shown in the following example:

The <remarks> tag is used to add an additional comment block to the documentation associated with a particular method. Discussion on previous tags has shown the <remarks> tag in action, but the syntax is as follows:

<remarks>
   Any further remarks go here
</remarks>

Normally, you would create a summary section, briefly outline the method or type, and then include the detailed information inside the <remarks> tag, with the expected outcomes of accessing the member.

When a method returns a value to the calling code, you can use the <returns> tag to describe what it could be. The syntax of <returns> is like most of the other block-level tags, consisting of an opening and closing tag with any information detailing the return value enclosed within:

<returns>
   Description of the return value.
</returns>

A simple implementation of <returns> might appear like the following code:

You can add references to other items in the project using the <see> tag. Like some of the other tags already discussed, the <see> tag requires a cref attribute with a value equal to an existing member, whether it is a property, method, or class definition. The <see> tag is used inline with other areas of the documentation such as <summary> or <remarks>. The syntax is as follows:

<see cref="memberName" />

When Visual Studio processes the <see> tag it produces a fully qualified address that can then be used as the basis for a link in the documentation when transformed via style sheets. For example, referring to an application with a class containing a function named ChangePwd would result in the following cref value:

<see cref="applicationName.className.ChangePwd"/>

The following example uses the <see> tag to provide a link to another function called CheckUser:

The <seealso> tag is used to generate a separate section containing information about related topics within the documentation. Rather than being inline like <see>, the <seealso> tags are defined outside the other XML comment blocks, with each instance of <seealso> requiring a cref attribute containing the name of the property, method, or class to which to link. The full syntax appears like so:

<seealso cref="memberName" />

Modifying the previous example, the following code shows how the <seealso> tag can be implemented in code:

The <summary> tag is used to provide the brief description that appears at the top of a specific topic in the documentation. As such it is typically placed before all public and protected methods and classes. In addition, the <summary> area is used for Visual Studio's IntelliSense engine when using your own custom-built code. The syntax to implement <summary> is as follows:

<summary>
   A description of the function or property goes here.
</summary>

The <typeparam> tag provides information about the type parameters when dealing with a generic type or member definition. The <typeparam> tag expects an attribute of name containing the type parameter being referred to:

<typeparam name="typeName">
   Description goes here.
</typeparam>

You can use <typeparam> in either C# or VB, as the following code shows:

If you are referring to a generic type parameter elsewhere in the documentation other than the <typeparam> tag, you can use the <typeparamref> tag to format the value, or even link to the parameter information depending on how you code the XML transformation.

<typeparamref name="parameterName" />

Normally, <typeparamref> tags are used when you are referring to parameters in the larger sections of documentation such as the <summary> or <remarks> tags, as the following code demonstrates:

Normally used to define a property's purpose, the <value> tag gives you another section in the XML where you can provide information about the associated member. The <value> tag is not used by IntelliSense.

<value>The text to display</value>

When used in conjunction with a property, you would normally use the <summary> tag to describe what the property is for, whereas the <value> tag is used to describe what the property represents: