<include> (C# Programming Guide)

The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.

<include file='filename' path='tagpath[@name="id"]' />

Parameters

• filename
  The name of the XML file containing the documentation. The file name can be qualified with a path. Enclose filename in single quotation marks (' ').

• tagpath
  The path of the tags in filename that leads to the tag name. Enclose the path in single quotation marks (' ').

• name
  The name specifier in the tag that precedes the comments; name will have an id.

• id
  The ID for the tag that precedes the comments. Enclose the ID in double quotation marks (" ").

Remarks

By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out.

The <include> tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your <include> use.

Example

This is a multifile example. The first file, which uses <include>, is listed below:

// compile with: /doc:DocFileName.xml 

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
    static void Main()
    {
    }
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
    public void Test()
    {
    }
}

The second file, xml_include_tag.doc, contains the following documentation comments:

<MyDocs>

<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>

<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>

</MyDocs>

Program Output

The following output is generated when you compile the Test and Test2 classes with the following command line: /doc:DocFileName.xml. In Visual Studio, you specify the XML doc comments option in the Build pane of the Project Designer. When the C# compiler sees the <include> tag, it searches for documentation comments in xml_include_tag.doc instead of the current source file. The compiler then generates DocFileName.xml, and this is the file that is consumed by documentation tools such as Sandcastle to produce the final documentation.

<?xml version="1.0"?> 
<doc> 
    <assembly> 
        <name>xml_include_tag</name> 
    </assembly> 
    <members> 
        <member name="T:Test"> 
            <summary> 
The summary for this type. 
</summary> 
        </member> 
        <member name="T:Test2"> 
            <summary> 
The summary for this other type. 
</summary> 
        </member> 
    </members> 
</doc> 

See Also

Concepts

C# Programming Guide

Reference

Recommended Tags for Documentation Comments (C# Programming Guide)