<include> (Руководство по программированию на C#)

Статья
08/11/2011

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

Параметры

filename
Имя файла XML, содержащего документацию. Имя файла может быть дополнено путем. Заключите filename в одинарные кавычки (' ').
tagpath
Путь тегов в filename, который приводит к тегу name. Заключите путь в одинарные кавычки (' ').
name
Спецификатор имени в теге, который предшествует комментариям; name будет иметь id.
id
Идентификатор для тега, который предшествует комментариям. Заключите идентификатор в двойные кавычки (" ").

Заметки

Используйте тег <include> для ссылок на комментарии в другом файле, описывающем типы и элементы в исходном коде. Это является альтернативой помещению комментариев документации непосредственно в файле исходного кода. Поместив документацию в отдельный файл, можно применять систему управления версиями в документации отдельно от исходного кода. Один человек может иметь извлеченный файл исходного кода, а другой — извлеченный файл документации.

Тег <include> использует синтаксис XPath XML. Сведения о способах настройки использования тега <include> см. в документации по XPath.

Пример

В данном примере используется несколько файлов. Первый файл, использующий тег <include>, указан ниже.

// 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()
    {
    }
}

Второй файл — xml_include_tag.doc — содержит следующие комментарии к документации.

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

Выходные данные программы

Следующие выходные данные создаются при компиляции классов Test и Test2 с помощью следующей командной строки: /doc:DocFileName.xml.. В Visual Studio параметр комментариев документации XML задается в области построения конструктора проектов. Когда компилятор C# находит тег <inclue>, он выполняет поиск комментариев документации в файле xml_include_tag.doc, а не в текущем исходном файле. Затем компилятор создает файл DocFileName.xml, и этот файл используется средствами документации, такими как Sandcastle, для создания окончательной документации.

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

См. также

Ссылки

Основные понятия

Руководство по программированию на C#

Поделиться через