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>		Указать, что слово является именем параметра типа

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 { // ... }

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; }

3. <example>

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

Синтаксис:

<example>description</example>

Пример.

См. пример для <c> (§A.2.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(); // … } }

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 { … }

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 () { // ... } }

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() { // ... }

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; }

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; }

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() { // ... }

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 { // ... }

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 + ")"; }

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; }

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) { // ... }

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) { }

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; } }

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> { ... }

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) { ... }