Обработка XML-файлов документации
Компилятор создает строку идентификатора для каждой конструкции в коде, помеченной для создания документации. Дополнительные сведения см . в комментариях к рекомендуемой документации по тегам. Строка идентификатора однозначно определяет конструкцию. Программы, обрабатывающие XML-файл, могут использовать строку идентификатора для идентификации соответствующего платформа .NET Framework метаданных или элемента отражения, к которому применяется документация.
XML-файл не является иерархическим представлением кода, это плоский список с созданным идентификатором для каждого элемента.
Компилятор соблюдает следующие правила при формировании строк идентификаторов.
Пробелы в строку не вставляются.
Первая часть строки идентификатора определяет тип идентифицируемого члена. Это один символ, за которым следует двоеточие. Используются следующие типы элементов.
Символ Description N Пространство имен
Невозможно добавить комментарии к документации в пространство имен, ссылки на пространство имен возможны.T Тип: класс, интерфейс, структура, перечисление, делегат D Typedef F Поле P Свойство (включая индексаторы или другие индексированные свойства) Пн. Метод (включая такие специальные методы, как конструкторы, операторы и т. д.) E Мероприятие ! Строка ошибки
Остальная часть строки предоставляет сведения об ошибке. Компилятор MSVC создает сведения об ошибке для ссылок, которые не могут быть разрешены.Вторая часть строки содержит полное имя элемента, начиная от корня пространства имен. Имя элемента, включающие типы и пространство имен разделяются точками. Если в имени самого элемента есть точки, они заменяются символами решетки ("#"). Предполагается, что в именах элементов не может содержаться символ решетки. Например, полное имя конструктора
StringбудетSystem.String.#ctor.Для свойств и методов, имеющих аргументы, список этих аргументов заключается в круглые скобки и указывается в конце. Если аргументы не используются, скобки отсутствуют. Аргументы разделяются запятыми. Каждый аргумент закодирован так же, как кодируется в сигнатуре платформа .NET Framework:
Базовые типы. Обычные типы (
ELEMENT_TYPE_CLASSилиELEMENT_TYPE_VALUETYPE) представляются в виде полного имени типа.Встроенные типы (например,
ELEMENT_TYPE_I4, ,ELEMENT_TYPE_STRINGELEMENT_TYPE_OBJECTELEMENT_TYPE_TYPEDBYREF, иELEMENT_TYPE_VOID) представляются как полное имя соответствующего полного типа, напримерSystem.Int32или .System.TypedReferenceELEMENT_TYPE_PTRпредставляется в виде "*" после имени измененного типа.ELEMENT_TYPE_BYREFпредставляется в виде "@" после имени измененного типа.ELEMENT_TYPE_PINNEDпредставляется в виде "^" после имени измененного типа. Компилятор MSVC никогда не создает этот элемент.ELEMENT_TYPE_CMOD_REQпредставляется как "|" и полное имя класса модификатора после измененного типа. Компилятор MSVC никогда не создает этот элемент.ELEMENT_TYPE_CMOD_OPTпредставляется как "!" и полное имя класса модификатора после измененного типа.ELEMENT_TYPE_SZARRAYпредставляется как "[]" после типа элемента массива.ELEMENT_TYPE_GENERICARRAYпредставляется как "[?]" после типа элемента массива. Компилятор MSVC никогда не создает этот элемент.ELEMENT_TYPE_ARRAYпредставляется как[нижний размер нижней границы]:,:, где число запятых — 1, а нижняя граница и размер каждого измерения, если известно, представлены в десятичном разряде. Если нижняя граница или размер не указаны, они опускаются. Если нижнюю границу и размер опущены для определенного измерения, то ":" также опущен. Например, 2-мерный массив с 1 нижней границой и неопределенными размерами представлен как[1:,1:].ELEMENT_TYPE_FNPTRпредставляется как "=FUNC:type(подпись)", гдеtypeобозначает возвращаемый тип, а подпись представляет аргументы метода. Если аргументы не используются, скобки опускаются. Компилятор MSVC никогда не создает этот элемент.
Следующие компоненты подписи не представлены, так как они никогда не используются для разных перегруженных методов:
Соглашение о вызовах
Возвращаемый тип
ELEMENT_TYPE_SENTINEL
Только для операторов преобразования возвращаемое значение метода закодировано как "
~", за которым следует тип возвращаемого значения, как было закодировано ранее.Для универсальных типов имя типа завершается символом обратного апострофа и числом, которое обозначает количество параметров универсального типа. Например,
<member name="T:MyClass`2">В примере показан тип, определенный как
public class MyClass<T, U>.Для методов, которые принимают универсальные типы в качестве параметров, параметры универсального типа указываются в виде чисел, предопределенных обратными галками (например, 0, 1). Каждое число представляет позицию массива на основе нуля для универсальных параметров типа.
Пример
Примеры ниже демонстрируют, как создаются строки идентификатора для класса и его элементов.
// xml_id_strings.cpp
// compile with: /clr /doc /LD
///
namespace N {
// "N:N"
/// <see cref="System" />
// <see cref="N:System"/>
ref class X {
// "T:N.X"
protected:
///
!X(){}
// "M:N.X.Finalize", destructor's representation in metadata
public:
///
X() {}
// "M:N.X.#ctor"
///
static X() {}
// "M:N.X.#cctor"
///
X(int i) {}
// "M:N.X.#ctor(System.Int32)"
///
~X() {}
// "M:N.X.Dispose", Dispose function representation in metadata
///
System::String^ q;
// "F:N.X.q"
///
double PI;
// "F:N.X.PI"
///
int f() { return 1; }
// "M:N.X.f"
///
int bb(System::String ^ s, int % y, void * z) { return 1; }
// "M:N.X.bb(System.String,System.Int32@,System.Void*)"
///
int gg(array<short> ^ array1, array< int, 2 >^ IntArray) { return 0; }
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
///
static X^ operator+(X^ x, X^ xx) { return x; }
// "M:N.X.op_Addition(N.X,N.X)"
///
property int prop;
// "M:N.X.prop"
///
property int prop2 {
// "P:N.X.prop2"
///
int get() { return 0; }
// M:N.X.get_prop2
///
void set(int i) {}
// M:N.X.set_prop2(System.Int32)
}
///
delegate void D(int i);
// "T:N.X.D"
///
event D ^ d;
// "E:N.X.d"
///
ref class Nested {};
// "T:N.X.Nested"
///
static explicit operator System::Int32 (X x) { return 1; }
// "M:N.X.op_Explicit(N.X!System.Runtime.CompilerServices.IsByValue)~System.Int32"
};
}