Студопедия
Случайная страница | ТОМ-1 | ТОМ-2 | ТОМ-3
АрхитектураБиологияГеографияДругоеИностранные языки
ИнформатикаИсторияКультураЛитератураМатематика
МедицинаМеханикаОбразованиеОхрана трудаПедагогика
ПолитикаПравоПрограммированиеПсихологияРелигия
СоциологияСпортСтроительствоФизикаФилософия
ФинансыХимияЭкологияЭкономикаЭлектроника

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

Pragma warning 10 страница | Pragma warning 13 страница | From, let, where, join и orderby 1 страница | Using namespace 21 страница | GetEnumerator 1 страница | GetEnumerator 5 страница | GetEnumerator 13 страница | COM и Win32 12 страница |


Читайте также:
  1. 1 страница
  2. 1 страница
  3. 1 страница
  4. 1 страница
  5. 1 страница
  6. 1 страница
  7. 1 страница

· тег <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; просмотров: 54 | Нарушение авторских прав


<== предыдущая страница | следующая страница ==>
AttributeUsage| COM и Win32 11 страница

mybiblioteka.su - 2015-2024 год. (0.014 сек.)