Obsolete 11 страница

Каждый элемент списка задается блоком <item>. При создании списка определений необходимо задать и термин, и описание. Но для таблицы, маркированного списка или нумерованного списка необходимо задать только описание.

Синтаксис:

<list type="bullet" | "number" | "table">
<listheader>
<term> term </term>
<description> description </description>
</listheader>
<item>
<term> term </term>
<description> description </description>
</item>
…
<item>
<term> term </term>
<description> description </description>
</item>
</list>

где

term

определяемый термин, определенный в описание;.

description

либо элемент маркированного или нумерованного списка, либо определение термина;.

Пример:

public class MyClass
{
/// <summary>Here is an example of a bulleted list:
/// <list type="bullet">
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// </summary>
public static void Main () {
//...
}
}

A.2.7 <para>

Этот тег используется внутри других тегов, таких как <summary> (§A.2.11) или <returns> (§A.2.12), и позволяет добавить структуру к тексту.

Синтаксис:

<para> content </para>

где

content

текст абзаца.

Пример:

/// <summary>This is the entry point of the Point class testing program.
/// <para>This program tests each method and operator, and
/// is intended to be run after any non-trvial maintenance has
/// been performed on the Point class.</para></summary>
public static void Main() {
//...
}

A.2.8 <param>

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

Синтаксис:

<param name=" name "> description </param>

где

name

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

description

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

Пример:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <param name="xor">the new x-coordinate.</param>
/// <param name="yor">the new y-coordinate.</param>
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}

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	Тип (такой как класс, делегат, перечисление, интерфейс или структура)
!	Строка ошибки; в остальной части строки приведены сведения об ошибке. Например, генератор документации создает сведения об ошибке для ссылок, которые не удается разрешить.