Обработка XML-файла (Руководство по программированию на C#)
Компилятор создает строку идентификатора для каждой конструкции в коде, отмеченной для создания документации (Сведения о создании тегов в коде см. в разделе Рекомендуемые теги для комментариев документации.) Строка идентификатора однозначно определяет конструкцию. Программы обработки XML-файлов могут использовать строку идентификатора для идентификации соответствующего элемента метаданных или отражений .NET Framework, к которому применяется документация.
XML-файл не является иерархическим представлением кода; он содержит список с созданным идентификатором для каждого элемента.
Компилятор следует приведенным ниже правилам при формировании строк идентификаторов:
Отсутствие пробела в строке.
Первая часть строки идентификатора определяет тип идентифицируемого члена в виде одного символа с последующим двоеточием. Используются следующие типы элементов.
Знак
Описание
N
Пространству имен
Нельзя добавлять комментарии документации к пространству имен, но можно создать CREF-ссылки на них, если они поддерживаются.
T
тип: класс, интерфейс, структура, перечисление, делегат
F
поле
P
свойство (включая индексаторы или другие индексированные свойства)
M
метод (включая такие специальные методы как конструкторы, операторы и так далее)
E
event
!
Строка ошибки
Остальная часть строки содержит сведения об ошибке. Компилятор C# создает сведения об ошибках для ссылок, которые не могут быть разрешены.
Вторая часть строки – это полное имя элемента, начиная с корневого пространства имен. Имя элемента, включающий его тип и пространство имен разделяются точками. Если имя элемента содержит точки, они заменяются решетками (#). Предполагается, что элемент не имеет символов решетки непосредственно в имени. Например, полное имя конструктора 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.Int32 или System.TypedReference.
ELEMENT_TYPE_PTR представлен символом звездочки (“*”) после измененного типа.
ELEMENT_TYPE_BYREF представлен символом “@” после измененного типа.
ELEMENT_TYPE_PINNED представлен символом “^” после измененного типа. Компилятор C# не создает этот тип.
ELEMENT_TYPE_CMOD_REQ представлен символом “|” и полным именем класса модификатора после измененного типа. Компилятор C# не создает этот тип.
ELEMENT_TYPE_CMOD_OPT представляется символом "!" и полным именем класса модификатора после измененного типа.
ELEMENT_TYPE_SZARRAY представлен символом “[]” после типа элемента массива.
ELEMENT_TYPE_GENERICARRAY представлен символом “[?]” после типа элемента массива. Компилятор C# не создает этот тип.
ELEMENT_TYPE_ARRAY представлен [нижняя граница:size,нижняя граница:size], где число запятых это ранг - 1, а нижние границы и размер каждой размерности (если они известны) представлены десятичными числами. Если нижняя граница или размер не указаны, они просто опускаются. Если нижняя граница и размер для определенной размерности опущены, “:” также опускается. Например, двухмерный массив с 1 в качестве нижних границ и незаданными размерами – [1:,1:].
ELEMENT_TYPE_FNPTR представлен "=FUNC:type(сигнатура)", где type – возвращаемый тип, а сигнатура – аргументы метода. Если аргументы отсутствуют, скобки опускаются. Компилятор C# не создает этот тип.
Следующие компоненты сигнатуры не представляются, так как они никогда не используются для разграничения перегруженных методов:
соглашение при вызове
возвращаемый тип
ELEMENT_TYPE_SENTINEL
Только для операторов преобразования (op_Implicit и op_Explicit) возвращаемое значение кодируется в виде “~” с последующим возвращаемым типом как закодировано выше.
Для универсальных типов после имени типа будет следовать символ “`”, а затем число, указывающее количество параметров универсальных типов. Например:
<member name="T:SampleClass`2"> является тегом для типа, определенного как public class SampleClass<T, U>.
Для методов, принимающих в качестве параметров универсальные типы, параметры универсальных типов указываются в виде чисел, которым предшествуют символы “`” (например, `0,`1). Каждое число, представляющее нулевую нотацию массива для универсальных параметров типа.
Примеры
В следующих примерах показано как создаются строки идентификаторов для класса и его членов.
namespace N
{
/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:N.X".
/// </summary>
public unsafe class X
{
/// <summary>
/// Enter description here for the first constructor.
/// ID string generated is "M:N.X.#ctor".
/// </summary>
public X() { }
/// <summary>
/// Enter description here for the second constructor.
/// ID string generated is "M:N.X.#ctor(System.Int32)".
/// </summary>
/// <param name="i">Describe parameter.</param>
public X(int i) { }
/// <summary>
/// Enter description here for field q.
/// ID string generated is "F:N.X.q".
/// </summary>
public string q;
/// <summary>
/// Enter description for constant PI.
/// ID string generated is "F:N.X.PI".
/// </summary>
public const double PI = 3.14;
/// <summary>
/// Enter description for method f.
/// ID string generated is "M:N.X.f".
/// </summary>
/// <returns>Describe return value.</returns>
public int f() { return 1; }
/// <summary>
/// Enter description for method bb.
/// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <param name="y">Describe parameter.</param>
/// <param name="z">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int bb(string s, ref int y, void* z) { return 1; }
/// <summary>
/// Enter description for method gg.
/// ID string generated is "M:N.X.gg(System.Int16[],System.Int32[0:,0:])".
/// </summary>
/// <param name="array1">Describe parameter.</param>
/// <param name="array">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int gg(short[] array1, int[,] array) { return 0; }
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Addition(N.X,N.X)".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <param name="xx">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static X operator +(X x, X xx) { return x; }
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.prop".
/// </summary>
public int prop { get { return 1; } set { } }
/// <summary>
/// Enter description for event.
/// ID string generated is "E:N.X.d".
/// </summary>
public event D d;
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.Item(System.String)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <returns></returns>
public int this[string s] { get { return 1; } }
/// <summary>
/// Enter description for class Nested.
/// ID string generated is "T:N.X.Nested".
/// </summary>
public class Nested { }
/// <summary>
/// Enter description for delegate.
/// ID string generated is "T:N.X.D".
/// </summary>
/// <param name="i">Describe parameter.</param>
public delegate void D(int i);
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Explicit(N.X)~System.Int32".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static explicit operator int(X x) { return 1; }
}
}
См. также
Ссылки
/doc (параметры компилятора C#)
Комментарии к XML-документации (Руководство по программированию на C#)