Obsolete 11 страница.

A.2.9 Тег <paramref>

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

Синтаксис:

<paramref name=" имя;"/>

где

имя;

имя параметра.

Пример;.

/// <summary>Этот конструктор инициализирует новый Point с параметрами
/// (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param name="xor">новая координата x точки.</param>
/// <param name="yor">новая координата y точки.</param>

public Point(int xor, int yor) {
X = xor;
Y = yor;
}

A.2.10 Тег <permission>

Этот тег дает возможность документировать специальные возможности безопасности члена.

Синтаксис:

<permission cref="член">описание</permission>

где

cref=" член;"

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

описание;

описание доступа к члену.

Пример;.

/// <permission cref="System.Security.PermissionSet">Все могут
/// получить доступ к этому методу.</permission>

public static void Test() {
//...
}

A.2.11 Тег <summary>

Этот тег используется для указания общих сведений о типе. (Используйте <summary> (§A.2.15) для описания членов типа.)

Синтаксис:

<summary> описание;</summary>

где

описание;

текст общих сведений.

Пример;.

/// <summary>Класс <c>Point</c> моделирует точку
/// в двумерной плоскости.</summary>
///
public class Point
{
//...
}

A.2.12 Тег <returns>

Этот тег используется для описания возвращаемого методом значения.

Синтаксис:

<returns> описание;</returns>

где

описание;

описание возвращаемого значения.

Пример;.

/// <summary>Сообщает положение точки в виде строки.</summary>
/// <returns>Строка, представляющая положение точки в виде (x,y),
/// без пустого пространства в начале, конце или внутри.</returns>
public override string ToString() {
return "(" + X + "," + Y + ")";
}

A.2.13 Тег <see>

Этот тег дает возможность указать ссылку внутри текста. Используйте <seealso> (§A.2.14) для указания текста, который должен быть представлен в разделе See Also.

Синтаксис:

<see cref=" член;"/>

где

cref=" член;"

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

Пример;.

/// <summary>Этот метод изменяет положение точки
/// на заданные координаты.</summary>
/// <see cref="Translate"/>
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}

/// <summary>Этот метод изменяет положение точки
/// на заданное смещение x и y.
/// </summary>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

A.2.14 Тег <seealso>

Этот тег дает возможность создания записи для раздела See Also. Используйте <see> (§A.2.13) для указания ссылки изнутри текста.

Синтаксис:

<seealso cref=" член;"/>

где

cref=" член;"

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

Пример;.

/// <summary>Этот метод определяет, находятся ли две точки в одном
/// месте.</summary>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o) {
//...
}

A.2.15 Тег <summary>

Этот тег используется для описания члена типа. Используйте <summary> (§A.2.11) для описания самого типа.

Синтаксис:

<summary> описание;</summary>

где

описание

общие сведения о члене.

Пример;.

/// <summary>Этот конструктор инициализирует новый Point значениями (0,0).</summary>
public Point(): this(0,0) {
}

A.2.16 Тег <value>

Этот тег дает возможность описать свойство.

Синтаксис:

<value> описание свойства;</value>

где

описание свойства

описание свойства.

Пример;.

/// <value>Свойство <c>X</c> представляет координату x точки.</value>
public int X
{
get { return x; }
set { x = value; }
}

A.2.17 Тег <typeparam>

Этот тег используется для описания параметра универсального типа для класса, структуры, интерфейса, делегата и метода.

Синтаксис:

<typeparam name=" имя;"> описание;</typeparam>

где

имя

имя параметра типа.

описание

описание параметра типа.

Пример;.

/// <summary>Универсальный класс списка.</summary>
/// <typeparam name="T">Тип, сохраненный списком.</typeparam>
public class MyList<T> {
...
}

A.2.18 Тег <typeparamref>

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

Синтаксис:

<typeparamref name=" имя;"/>

где

имя;

имя параметра типа.

Пример;.

/// <summary>Этот метод выбирает данные и возвращает список <typeparamref name=”T”> ”/>”>.</summary>
/// <param name="string">запрос для выполнения</param>

public List<T> FetchData<T>(string query) {
...
}

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

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

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

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

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

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

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

 

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

 

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