<рага>

Элемент <рага> используется для разделения текста на абзацы:

/ <summary>

/ <рага>1-й абзац краткого 011иса1шя. </рага> / <рага>2-й абзац краткого описания.</parа>

/ </summary>

<с> и <code>

Оба элемента <с> и <code> используются для форматирования шрифтом кода, обычно моноширинным шрифтом, таким как Courier. Различие между ними в том, что элемент <с> представляет код в тексте , т.е. кодовые слова, встречающиеся внутри предложений, а <code> служит для форматирования фрагментов кода вне текста. Элементы <с> и <code> могут использоваться следующим образом:

/ <summary> / <рага>

/ Это краткое описание посвящено <с>классу</с> с интересными возможностями. / Попробуйте это:

/ </рага> / <code>

/ MyPoet poet = new MyPoet( Homer ) ; / poet.AddMuse( Thalia ) ; / poet.WriteMeAnEpicO ;

/ </code> / </summary>

<see>, <seealso>, <parainref > и <typeparainref >

Bee эти четыре элемента используются для ссылки на другие записи в XML-документации проекта или на внешние записи MSDN. Обычно каждый из них будет отображаться в виде гиперссылки, позволяя браузерам документации выполнять переход к другим записям.

Элементы <see> и <seealso> указывают свой целевой объект с помощью атрибута cref, причем целевым объектом может быть любой тип или член любого класса, в проекте или где-либо. Элементы <paramref > и <typeparamref > используют атрибут name для ссылки на параметр текущего целевого объекта:

/ <summary> / <рага>

/ Этот метод использует <paramre£ name= museName /> для выбора музы. / Для получения дополнительной информации см. <see cre£= MyPoet />.

/ </para>

/ <seealso cref= MyParchment /> / <seealso cref= MyTheme />

/ </summary>

Элемент <see> может быть особенно полезен для ссылки на ключевые слова С# посредством другого атрибута - langword.

/ <summary>

/ Для получения дополнительной информации см. <see langword= null />.

/ </summary>

Преимущество этого подхода в том, что указание ключевого слова, специфичного для языка, позволяет подготавливать документацию к другим языкам, таким как Visual Basic. Ключевое слово null в С# эквивалентно ключевому слову Nothing в Visual Basic, поэтому возможно обслуживание обоих языков - при условии, что подобные нюансы известны средству, используемому для форматирования XML-документации.

Обратите внимание, что элементы не включают в себя текст, предназначенный для отображения, который, как правило, создается атрибутами name, cref или langword. Это обстоятельство следует иметь в виду во избежание повторения текста - например:

/ Этот метод использует <paramref name= museName /> museName для выбора музы.

По всей видимости, в этом примере слово museName будет повторено.

<list> и связанные с ним элементы

Элемент <list> - наиболее сложный элемент форматирования текста, поскольку он может использоваться различными способами. Этот элемент обладает атрибутом type, который может принимать любое из следующих значений:

□ bullet - форматирует маркированный список;

□ number - форматирует нумерованный список; а table - форматирует таблицу.

Как правило, элемент <list> содержит один дочерний элемент <listheader> и несколько дочерних элементов <item>. Каждый из них может содержать дочерние элементы <term> и <description>. Выбор конкретного дочернего элемента будет зависеть от типа списка и способа форматирования списков выбранным средством. Например, элемент <term> может присутствовать или отсутствовать в списках в виде таблицы, в то время как элемент <listheader> имеет смысл только в таблице. Для маркированных списков можно применять код, подобный следующему:

/ <summary> / <рага>

/ Этот метод использует <paramref name= museName /> для выбора музы. / </рага> / <рага>

/ Попробуйте следующие музы: / <list type= bullet > / <listheader> / <term>Muse name</terin>

/ <description:use s favorite pizza</description> / </listheader> / <item>

/ <terin>Calliope</terin>

/ <description>Ham &amp; Mushroom</description> / </item> / <item>

/ <terin>Clio</terin>

/ <description>Four Seasons</description> / </item> / <item>

/ <terin>Erato</terin>

/ <description>Meat Feast</description> / </item> / </list>

/ </para> / </summary>

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

Основные структурные элементы

Несколько элементов, перечисленных в табл. 31.1, предназначены для использования в качестве элементов верхнего уровня в описании конкретного целевого объекта. Как было показано ранее, элемент <summary> служит ярким примером. Этот элемент никогда не должен входить в состав другого элемента и всегда используется для предоставления краткой информации о целевом объекте. Другие элементы, соответствующие этому описанию - <ехатр1е>, <exception>, <param>, <permission>, <remarks>, <returns> и <value>. Элемент <seealso> представляет особый случай элемента, который может быть как элементом верхнего уровня, так и дочерним элементом другого элемента. <include> - еще один особый случай элемента, поскольку он по существу замещает другие элементы, загружая XML-код из внешнего файла.

Рассмотрим эти элементы по очереди.

<siimmary>, <exaiiiple> и <rexnarks>

Каждый из этих трех элементов предоставляет общую информацию о целевом объекте. Мы уже встречались с элементом <suminary>, который можно использовать для вывода основной информации о целевом объекте. Поскольку эта информация отображается в подсказках инструмента, ее целесообразно хранить краткой. Дополнительную информацию следует помещать в элементы <ехатр1е> и <remarks>.

Часто при представлении класса полезно приводить пример его использования. Это же относится к методам, свойствам и т.п. Вместо того чтобы вставлять эту информацию в элемент <suminary>, имеет смысл поместить ее в новый раздел <ехатр1е>.

/ <summary> / <рага>

/ Это краткое описание посвящено <с>классу</с> с интересными возможностями. / </рага> / </summary> / <exainple> / <para>

/ Попробуйте следующее: / </рага> / <code>

/ MyPoet poet = new MyPoet ( Homer ) ; / poet.AddMuse ( Thalia ) ; / poet.WriteMeAnEpicO ; / </code> / </ехап5>1е>

Аналогично элемент <remarks> часто используют для предоставления более длинного описания целевого объекта. При этом он может содержать элементы <see> и <seealso>, определяющие перекрестные ссылки.

<param> и <typeparam>

Эти элементы описывают параметр - стандартный параметр метода либо параметр типа - обобщенных целевых объектов. Ссылка на параметр осуществляется с помощью атрибута name. При использовании нескольких параметров эти элементы могут встречаться несколько раз, как показано в следующем примере:

/ <summary>

/ Метод, используемый для добавления музы.

/ </summary>

/ <param name= museName >

/ Параметр <see langword= string /> укаэьтает гтя музы. / </param>