<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. 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.
This is a multifile example. The first file, which uses <include>, is listed below:
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>
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 <inclue> tag, it will search 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>