<include> Tag

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. 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.

Syntax

where:

filename

The name of the XML file containing the documentation. The file name can be qualified with a path.

tagpath

The path of the tags in filename that leads to the tag name.

name

The name specifier (attribute) in the tag that precedes the comments; name will have an id.

The ID for the tag that precedes the comments.

Examples

Let's have the following XML comments in the source code:

Visual Basic

Copy Code

''' <summary>Our sample property.</summary>

''' <include file="external_comments.xml"

''' path="doc/members/member[@name='TestDLL.DllClass1.prop1']/*" />

Property prop1() As String

Copy Code

/// <summary>Our sample property.</summary>

/// <include file="external_comments.xml"

/// path="doc/members/member[@name='TestDLL.DllClass1.prop1']/*" />

public string prop1

The external_comments.xml file contains the following:

Example

<?xml version="1.0" encoding="utf-8"?>

<doc>

This are remarks for prop1.

</remarks>

</member>

This are remarks for prop2.

</remarks>

</member>

</members>

</doc>

Then resulting XML comment for prop1 property will be:

Example

<summary>Our sample property.</summary>

This are remarks for prop1.

</remarks>