Obsolete 10 страница.

Хотя разработчики могут создавать свои собственные наборы тегов, рекомендуемый набор определен в §A.2. Некоторые из рекомендуемых тегов имеют специальные значения.

· тег <param> используется для описания параметров. Если используется этот тег, генератор документации должен проверить, что указанный параметр существует и что все параметры описаны в комментариях к документации. Если проверка неуспешна, генератор документации выдает предупреждение;

· атрибут cref можно привязать к любому тегу для создания ссылки на элемент кода. Генератор документации должен проверить, что этот элемент кода существует. Если проверка неуспешна, генератор документации выдает предупреждение. При поиске имени, описанного в атрибуте cref, генератор документации должен принимать во внимание видимость пространства имен в соответствии с операторами using, встречающимися в исходном коде. Для общих элементов кода нельзя использовать обычный универсальный синтаксис (т. е. "List<T>"), так как он создает неправильный XML. Можно использовать фигурные скобки вместо угловых (т. е. List{T}) или escape-синтаксис XML (т. е. List&lt;T&gt;);

· тег <summary> предназначен для использования средством просмотра документации для отображения дополнительных сведений о типе или члене;

· тег <include> включает сведения из внешнего XML-файла.

Внимательно отнеситесь к тому, что файл документации не предоставляет полные сведения о типе и членах (например, он не содержит никакие сведения о типе). Для получения таких сведений о типе или члене файл документации необходимо использовать в сочетании с соображениями по фактическому типу или члену.

A.2 Рекомендованные теги

Генератор документации обязан принять и обработать любой тег, допустимый по правилам XML. Следующие теги предоставляют обычно используемую функциональность в пользовательской документации (конечно, возможны и другие теги.)

 

Тег	Раздел	Назначение
<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	Документировать специальные возможности безопасности члена
<remark>	A.2.11	Предоставление дополнительных сведений о типе
<returns>	A.2.12	Описать возвращаемое методом значение
<see>	A.2.13	Указать ссылку
<seealso>	A.2.14	Создать запись См. также;
<summary>	A.2.15	Описание типа или члена типа
<value>	A.2.16	Описать свойство
<typeparam>		Описать параметр универсального типа
<typeparamref>		Указать, что слово является именем параметра типа

 

A.2.1 <c>

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

Синтаксис:

<c> text </c>

Пример:

/// <summary>Class <c>Point</c> models a point in a two-dimensional
/// plane.</summary>

public class Point
{
//...
}

A.2.2 <code>

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

Синтаксис:

<code> source code or program output </code>

Пример:

/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// <example>Например:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>

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

A.2.3 <example>

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

Синтаксис:

<example> description </example>

Пример;.

См. пример для <c> (§A.2.2).

A.2.4 <exception>

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

Синтаксис:

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

где

cref=" member "

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

description

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

Пример:

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=" filename " path= " xpath " />

где

file=" filename "

Имя внешнего 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>
Contains a list of integers.
</summary>
</class>
<class name= " StringList " >
<summary>
Contains a list of integers.
</summary>
</class>
</extradoc>

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

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

A.2.6 <list>

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