Обработка xml-файлов документации

Статья
06/16/2023

Компилятор создает строку идентификатора для каждой конструкции в коде, помеченной для создания документации. Дополнительные сведения см. в разделе Комментарии к документации по рекомендованным тегам. Строка идентификатора однозначно определяет конструкцию. Программы, обрабатывающие XML-файл, могут использовать строку идентификатора для идентификации соответствующих платформа .NET Framework метаданных или элемента отражения, к которому относится документация.

XML-файл не является иерархическим представлением кода, это неструктурированный список с созданным идентификатором для каждого элемента.

Компилятор соблюдает следующие правила при формировании строк идентификаторов.

Пробелы в строку не вставляются.

Первая часть строки идентификатора определяет тип идентифицируемого члена. Это один символ, за которым следует двоеточие. Используются следующие типы элементов.

Знак	Описание
Нет	Пространство имен Вы не можете добавлять комментарии документации к пространству имен. Возможны ссылки cref на пространство имен.
T	Тип: class, interface, struct, enum, delegate
D	Typedef
F	Поле
P	Свойство (включая индексаторы или другие индексированные свойства)
M	Метод (включая такие специальные методы, как конструкторы, операторы и т. д.)
E	Событие
!	Строка ошибки Остальная часть строки предоставляет сведения об ошибке. Компилятор MSVC создает сведения об ошибках для ссылок, которые не удается разрешить.

Вторая часть строки содержит полное имя элемента, начиная от корня пространства имен. Имя элемента, включающие типы и пространство имен разделяются точками. Если в имени самого элемента есть точки, они заменяются символами решетки ("#"). Предполагается, что в именах элементов не может содержаться символ решетки. Например, полное имя конструктора String будет иметь значение System.String.#ctor.
Для свойств и методов, имеющих аргументы, список этих аргументов заключается в круглые скобки и указывается в конце. Если аргументы не используются, скобки отсутствуют. Аргументы разделяются запятыми. Каждый аргумент кодируется так же, как и в сигнатуре платформа .NET Framework:
- Базовые типы. Обычные типы (ELEMENT_TYPE_CLASS или ELEMENT_TYPE_VALUETYPE) представляются в виде полного имени типа.
- Встроенные типы (например, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREFи ELEMENT_TYPE_VOID) представлены в виде полного имени соответствующего полного типа, например или System.Int32System.TypedReference.
- ELEMENT_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, а нижняя граница и размер каждого измерения, если они известны, представлены десятичным числом. Если нижняя граница или размер не указаны, они опускаются. Если нижняя граница и размер опущены для определенного измерения, значение ":" также опущено. Например, двухмерный массив с 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"
   };
}

См. также раздел

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

Share via

Обработка xml-файлов документации

Пример

См. также раздел

Обратная связь

Обратная связь

Дополнительные ресурсы