3. Обработка файла документации

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

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

1. Формат строки идентификатора

При создании строк идентификаторов генератор документации соблюдает следующие правила:

• в строку не заносятся пробелы;

• первая часть строки идентифицирует вид документируемого члена с помощью одного символа, за которым следует двоеточие. Определены следующие виды членов:

Символ	Описание
E	Событие
F	Поле
M	Метод (включая конструкторы, деструкторы и операторы)
N	Пространство имен
P	Свойство (включая индексаторы)
T	Тип (такой как класс, делегат, перечисление, интерфейс или структура)
!	Строка ошибки; в остальной части строки приведены сведения об ошибке. Например, генератор документации создает сведения об ошибке для ссылок, которые не удается разрешить.

• во второй части строки находится полное имя элемента, начиная от корня пространства имен. Имена элемента, вмещающих его типов и пространства имен разделены точками. Если в самом имени есть точки, они заменяются символами # (U+0023) (предполагается, что в именах элементов нет такого символа);

• для методов и свойств с аргументами следует список аргументов, заключенный в круглые скобки. Если аргументов нет, скобки опускаются. Аргументы разделяются запятыми. Кодирование каждого аргумента такое же, как у подписи CLI, заключается в следующем:

• аргументы представлены своими именами в документации, основанными на их полном имени, со следующими изменениями:

• к аргументам, представляющим универсальные типы, присоединяется символ «’», за которым следует число параметров типа;

• у аргументов с модификатором out или ref за именем типа следует @. Аргументы, передаваемые по значению или через params, не имеют специального обозначения;

• аргументы, являющиеся массивами, представляются как [ нижняя_граница : размер , … , нижняя_граница : размер ], где число запятых равно рангу минус один, а нижние границы и размер каждого измерения, если они известны, представляются десятичными числами. Если нижняя граница или размер не указаны, они опускаются. Если для отдельного измерения опущены и нижняя граница, и размер, то «:» тоже опускается. Массивы массивов представлены одним «[]» на каждый уровень:

• аргументы, имеющие типы указателей, отличные от void, представляются с помощью * вслед за именем типа. Указатель типа void представляется с помощью имени типа System.Void;

• аргументы, ссылающиеся на параметры универсального типа, определенные для типов, кодируются с помощью символа «`», за которым следует начинающийся с нуля индекс параметра типа;

• аргументы, использующие параметры универсального типа, определенные в методах, используют двойной обратный апостроф «``» вместо одинарного «`», используемого для типов;

• аргументы, ссылающиеся на построенные универсальные типы, кодируются с помощью универсального типа, за которым следует «{», затем разделенный запятыми список аргументов типа и затем «}».