COM и Win32 11 страница

A.2.9 <paramref>

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

Синтаксис:

<paramref name=" name "/>

где

name

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

Пример:

/// <summary>This constructor initializes the new Point to
/// (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param name="xor">the new Point's x-coordinate.</param>
/// <param name="yor">the new Point's y-coordinate.</param>

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

A.2.10 <permission>

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

Синтаксис:

<permission cref=" member "> description </permission>

где

cref=" member "

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

description

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

Пример:

/// <permission cref="System.Security.PermissionSet">Everyone can
/// access this method.</permission>

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

A.2.11 <remark>

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

Синтаксис:

<remark> description </remark>

где

description

Текст примечания.

Пример:

/// <summary>Class <c>Point</c> models a point in a
/// two-dimensional plane.</summary>
/// <remark>Uses polar coordinates</remark>
public class Point
{
//...
}

A.2.12 <returns>

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

Синтаксис:

<returns> description </returns>

где

description

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

Пример:

/// <summary>Report a point's location as a string.</summary>
/// <returns>A string representing a point's location, in the form (x,y),
/// without any leading, trailing, or embedded whitespace.</returns>
public override string ToString() {
return "(" + X + "," + Y + ")";
}

A.2.13 <see>

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

Синтаксис:

<see cref=" member "/>

где

cref=" member "

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

Пример:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <see cref="Translate"/>
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}

/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// </summary>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

A.2.14 <seealso>

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

Синтаксис:

<seealso cref=" member "/>

где

cref=" member "

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

Пример:

/// <summary>This method determines whether two Points have the same
/// location.</summary>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o) {
//...
}

A.2.15 <summary>

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

Синтаксис:

<summary> description </summary>

где

description

Сводные сведения о типе или члене.

Пример:

/// <summary>This constructor initializes the new Point to (0,0).</summary>
public Point(): this(0,0) {
}

A.2.16 <value>

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

Синтаксис:

<value> property description </value>

где

property description

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

Пример:

/// <value>Property <c>X</c> represents the point's x-coordinate.</value>
public int X
{
get { return x; }
set { x = value; }
}

A.2.17 <typeparam>

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

Синтаксис:

<typeparam name=" name "> description </typeparam>

где

name

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

description

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

Пример:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T> {
...
}

A.2.18 <typeparamref>

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

Синтаксис:

<typeparamref name=" name "/>

где

name

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

Пример:

/// <summary>This method fetches data and returns a list of <typeparamref name=”T”> ”/>”>.</summary>
/// <param name="string">query to execute</param>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дата добавления: 2015-11-14