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

· тег <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> для определения строки заголовка таблицы или списка определений (при определении таблицы необходимо предоставить только запись термина в заголовке.)

Каждый элемент списка задается блоком <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;
}

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