Практическое занятие

Добавление и просмотр основной ХМ L-документации

L Создайте новое консольное приложение FirstXMLDocumentation и сохраните его в каталоге С: \BegVCSharp\Chapter31.

2. Добавьте класс DocumentedClass.

3. Откройте код класса DocumentedClass, объявите определение класса общедоступным, добавьте новую строку перед объявлением класса и введите в ней символы /.

4. Обратите внимание, что функция автозавершения IDE добавляет следующий код, помещая курсор внутрь элемента <summary>.

namespace FirstXMLDocumentation {

/ <зи1шпагу> /

/ </зи1шпагу>

public class DocumentedClass {

5. Добавьте следующий текст в элемент <summary>: namespace FirstXMLDocumentation

/ <зи1шпагу>

/ This is a suimnary description for the DocumentedClass class. / </summary>

public class DocumentedClass {

6. В файле Program, cs введите doc в методе Main () и обратите внимание на открывшееся всплывающее окно с информацией IntelliSense, показанное на рис. 31.1.

lUFirjtXMlDocumemation Program 1[ Using System;

using System.Collect ions.Ceneric; using System.Linq: usin.i System.Text;

bi namespmce FirstXHLDocumentation

12 13

class Progrwn

sraric void Bain(?rrinj[] args)

doc)

Dirtionaryo

DivideByZfroExcepbon *; DIINotFoundException Л do

double Double

*tj DuphcateWBitObjectException iD else

Encoder

class FirslXMLOocumenialion DocumentedClass

This IS a summary descfipnon forihe DocumemedClass class

Puc. 31.1. Всплывающее окно с информацией IntelliSense

7. Откройте окно Object Browser (Браузер объектов) и разверните элемент проекта FirstXMLDocumentation вплоть до объекта DocumentedClass. Обратите внимание на краткую информацию, отображенную в нижней правой панели, как показано на рис. 31.2.

FirstxMlDocumentetion <1 FlrjtXMlDocumentation

ill

К Sf Program Microjon.Builcl.Convfriionv3 5 MicrosoflBuild Engine Miao5oft Build Frtmework Miaosoft Build Utlitiej v3 5 MicrosoftVlsualBesic Microsoft Vi5ualCSTlClR mscortib

PresentBtionBuilcnuki

PreientationCore

PrcjfntatlonFramewortr

Present ationFremework Aero

PreientationFrameworkClassic

PresentationFramework Luna

PreientationFramfw )rt Royaie

ReacriFrimewofk

System

System>ddln SyuemJkddln Contract System Configuration System ConftgurationJnstall

public class DocunentedClMt

Member of FittX.Pfxи<>£п14(ку}

This IS a Summary description for the DocumentedClass class.

Puc. 31.2. Отображение элемента XML-документации <sunmary>

Описание полученных результатов

Этот пример демонстрирует общую методику добавления XML-документации и использования этой документации в интегрированной среде разработки (IDE). При добавлении краткой информации о классе DocumentedClass мы видели, как IDE динамически определяет необходимые элементы информации и автоматически заполняет основную часть соответствующего кода. Средства IntelliSense и Object Browser выявляет документацию даже без компиляции проекта. Эта общая методика применима ко всем аспектам XML-документации и облегчает добавление и использование этой информации.

Комментарии XML-документации

Фактически в XML-документацию целевого объекта (под целевым объектом подразумевается тип или улен) можно добавлять любые элементы XML. Однако применение ряда рекомендуемых элементов и атрибутов будет способствовать тому, чтобы документация соответствовала стандартным рекомендациям. Рекомендуемых элементов XML достаточно для большинства ситуаций, и выполнение этого стандарта означает, что программные средства, в которых применяется XML-документация (в том числе IntelliSense и Object Browser), смогут эффективно ее использовать.

Краткое описание основных элементов XML-документации приведено в табл. 31.1. Подробнее они рассматриваются в последующих разделах.

Таблица 31.1. Основные элементы ХМL-документации

Элемент

Описание

<с>

<code>

<description>

<example> <exception> <include> <item>

<list>

<listheader>

<para>

<param>

<paramref>

<permission>

<remarks>

<returns>

<see>

<seealso>

<summary> <term>

<typeparam>

<typeparamref>

<value>

Форматирует текст с использованием шрифта кода. Применяйте этот элемент для отдельных кодовых слов, внедренных в другой текст

Форматирует текст с использованием шрифта кода. Применяйте этот элемент для нескольких строк кода, не являющихся внедренными в другой текст

Помечает текст в качестве описания элемента. Используется в качестве дочернего элемента элементов <item> или <listheader> в списках

Помечает текст в качестве примера использования целевого объекта

Указывает исключение, которое может порождаться целевым объектом

Извлекает XML-документацию из внешнего файла

Представляет элемент списка. Используется в качестве дочернего элемента для <list> и может иметь дочерние элементы <description> и <term>

Определяет список. Может иметь дочерние элементы <listheader> и <item>

Представляет строку заголовка табличного списка. Используется в качестве дочернего элемента для <list> и может иметь дочерние элементы

<description> и <term>

Используется для разбиения текста на отдельные абзацы

Описывает параметр целевого объекта

Определяет ссылку на параметр метода

Указывает разрешения, необходимые для целевого объекта

Содержит дополнительную информацию о целевом объекте

Описывает возвращаемое значение целевого объекта; используется с методами

Определяет ссылку на другой целевой объект, используемую в теле такого элемента, как <summary>

Определяет ссылку на другой целевой объект, обычно используемую вне других элементов или в конце элемента, например, <summary>

Содержит краткую информацию о целевом объекте

Помечает текст в качестве определения элемента. Используется в качестве дочернего элемента элементов <item> или <listheader> в списках

Описывает параметр типа обобщенного целевого объекта

Определяет ссылку на параметр типа

Описывает возвращаемое значение целевого объекта; используется с методами

Элементы форматирования текста

Многие из элементов, перечисленных в табл. 3L1, предназначены для форматирования текста внутри других элементов. Например, элемент <suminary> может содержать комбинацию других элементов, которые указшают текст, предназначенный для отображения. Элементы форматирования текста - <с>, <code>, <list> и связанные с ними элементы <рага>, <paramref > и <see>. Элемент <seealso> - особый случай, который можно также включить в этот список, поскольку его можно вставлять в тело текста, хотя обычно он встречается в конце.