Obsolete 10 страница

 

Тег	Раздел	Назначение
<c>	A.2.1	Установить шрифт текста, подобный исходному коду
<code>	A.2.2	Установить одну или несколько строк исходного кода или программного вывода
<example>	A.2.3	Указать пример
<exception>	A.2.4	Идентификация исключений, которые могут выдаваться методом
<include>	A.2.5	Включение XML из внешнего файла
<list>	A.2.6	Создание списка или таблицы
<para>	A.2.7	Разрешить добавление структуры к тексту
<param>	A.2.8	Описать параметр для метода или конструктора
<paramref>	A.2.9	Указать, что слово является именем параметра
<permission>	A.2.10	Документировать специальные возможности безопасности члена
<summary>	A.2.11	Описать тип
<returns>	A.2.12	Описать возвращаемое методом значение
<see>	A.2.13	Указать ссылку
<seealso>	A.2.14	Создать запись See Also
<summary>	A.2.15	Описать член типа
<value>	A.2.16	Описать свойство
<typeparam>		Описать параметр универсального типа
<typeparamref>		Указать, что слово является именем параметра типа

 

A.2.1 Тег <c>

Этот тег предоставляет механизм для указания, что для фрагмента текста внутри описания следует установить особый шрифт, такой как используемый для блока кода. Для строк фактического текста используйте тег <code> (§A.2.2).

Синтаксис:

<c> текст;</c>

Пример;.

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

public class Point
{
//...
}

A.2.2 Тег <code>

Этот тег используется для установки для одной или нескольких строк исходного кода или программного вывода особого шрифта. Для маленьких фрагментов кода в комментарии используйте <c> (§A.2.1).

Синтаксис:

<code> исходный код или программный вывод;</code>

Пример;.

/// <summary>Этот метод изменяет положение точки
/// на заданное смещение x и y.
/// <example>Например:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// дает в результате <c>p</c> со значением (2,8).
/// </example>
/// </summary>

public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

A.2.3 Тег <example>

Этот тег позволяет вставить пример кода в комментарий, чтобы указать, как можно использовать метод или другой член библиотеки. Обычно это влечет также и использование тега <code> (§A.2.2).

Синтаксис:

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

Пример;.

См. пример в <code> (§A.2.2).

A.2.4 Тег <exception>

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

Синтаксис:

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

где

cref=" член;"

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

описание;

Описание обстоятельств, при которых выдается это исключение.

Пример;.

public class DataBaseOperations
{
/// <exception cref="MasterFileFormatCorruptException"></exception>
/// <exception cref="MasterFileLockedOpenException"></exception>
public static void ReadRecord(int flag) {
if (flag == 1)
throw new MasterFileFormatCorruptException();
else if (flag == 2)
throw new MasterFileLockedOpenException();
// …
}
}

A.2.5 Тег <include>

Этот тег позволяет включать сведения из внешнего XML-документа в файл исходного кода. Внешний файл должен быть правильным XML-документом, а выражение XPath применяется к этому документу для указания, какой XML из этого документа требуется включить. Затем тег <include> заменяется выбранным XML из внешнего документа.

Синтаксис:

<include file=" имя_файла " path= " xpath " />

где

file=" имя_файла "

Имя внешнего XML-файла. Имя файла интерпретируется относительно файла, содержащего тег включения.

path= " xpath "

Выражение Xpath, выбирающее один из XML во внешнем XML-файле.

Пример.

Если в исходном коде содержится такое объявление:

/// <include file= " docs.xml " path= 'extradoc/class[@name="IntList"]/*' />
public class IntList { … }

а во внешнем файле " docs.xml " есть следующее содержимое:

<?xml version= "1.0"?>
<extradoc>
<class name= " IntList " >
<summary>
Содержит список целых чисел.
</summary>
</class>
<class name= " StringList " >
<summary>
Содержит список целых чисел.
</summary>
</class>
</extradoc>

тогда эта же документация выводится, как если бы исходный код содержал:

/// <summary>
/// Содержит список целых чисел.
/// </summary>
public class IntList { … }

A.2.6 Тег <list>

Этот тег используется для создания списка или таблицы элементов. Он может содержать блок <listheader> для определения строки заголовка таблицы или списка определений. (При определении таблицы необходимо предоставить только запись для термин; в заголовке.)

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

Синтаксис:

<list type="bullet" | "number" | "table">
<listheader>
<term> термин;</term>
<description> описание;</description>
</listheader>
<item>
<term> термин;</term>
<description> описание;</description>
</item>
…
<item>
<term> термин;</term>
<description> описание;</description>
</item>
</list>

где

термин;

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

описание

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

Пример;.

public class MyClass
{
/// <summary>Пример маркированного списка:
/// <list type="bullet">
/// <item>
/// <description>Элемент 1.</description>
/// </item>
/// <item>
/// <description>Элемент 2.</description>
/// </item>
/// </list>
/// </summary>
public static void Main () {
//...
}
}

A.2.7 Тег <para>

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

Синтаксис:

<para> содержимое;</para>

где

содержимое

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

Пример;.

/// <summary>Это точка входа программы тестирования класса Point.
/// <para>Эта программа тестирует каждый метод и оператор
/// и ее предполагается выполнять после каждого нетривиального
/// обслуживания класса Point.</para></summary>
public static void Main() {
//...
}

A.2.8 Тег <param>

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

Синтаксис:

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

где

имя

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

описание

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

Пример;.

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