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

<include> тег документации

  • Статья

Тег <include> позволяет задать ссылку на комментарии в другом файле, которые описывают типы и элементы вашего исходного кода. Этот тег является альтернативой размещению комментариев документации непосредственно в файле исходного кода. Например, можно использовать <include> для вставки стандартных комментариев", которые используются во всей команде или компании.

Синтаксис

/// <include file='filename' path='tag-path[@name="ID"' />

Параметры

filename
Имя файла, содержащего документацию. Имя файла может быть дополнено с указанием пути. Заключите имя в одинарные или двойные кавычки. Компилятор выдает предупреждение, если он не находит filename.

tag-path
Допустимое выражение XPath, которое выбирает нужный набор узлов, содержащийся в файле.

name
Спецификатор имени в теге, предшествующий комментариям. name будет иметь идентификатор ID.

ID
Идентификатор тега, который предшествует комментариям. Заключите идентификатор в одинарные или двойные кавычки.

Замечания

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

Скомпилируйте их для /doc обработки примечаний документации к файлу.

Пример

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

// xml_include_tag.cpp
// compile with: /clr /doc /LD
// post-build command: xdcmake xml_include_tag.dll

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

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
public ref class Test2 {
   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>

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

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>t2</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>

См. также

XML-документация