VBNet - Статьи - Документация XML в C#

Введение

XML комментарии, обозначаемые тройным слэшем (///), являются формой XML, используемой для документирования. Теги, используемые в комментариях, полностью настраиваемые; однако есть ряд тегов, которые согласованы с ECMA. Рекомендуемые теги имеют определенные значения для C# компилятора и Visual Studio IDE, но разработчики могут расширять этот рекомендуемый набор, чтобы проводить в жизнь корпоративные стандарты ведения документации, обеспечивать команды разработчиков совместимыми вариантами форматирования или добавлять любую дополнительную, по их мнению, необходимую информацию. Единственным ограничением в XML комментариях является то, что XML, размещенный в тегах, должен быть правильно построен. Это требование выдвигается C# компилятором, как частью процесса компиляции.

Использование XML комментариев

C# разработчики могут использовать XML комментарии, чтобы документировать код определенных пользователем типов, включая классы, делегаты, перечисления и структуры. Кроме того, XML комментарии могут быть применены к членам, включая поля, события, свойства, индексаторы и методы. Однако XML комментарии в настоящее время не поддерживаются для документирования пространств имен.

XML комментарии и Visual Studio .NET

Visual Studio .NET автоматически распознает и использует рекомендуемый набор тегов для создания собственной IntelliSense документации. Три наиболее важных рекомендуемых тега: <param>, <summary> и <remarks>. Теги <param> и <summary> используются в Intellisense, в то время как все три тега используются в VS ObjectBrowser.

Кроме того, к подмножеству XML тегов может быть добавлен атрибут cref (подробности см. в секции тегов), и тогда C# компилятор будет определять его в вашем коде. Этот тег обеспечивает возможность комментарию обращаться к элементу кода, находящемуся в другом месте источника.

Создание документированного компонента

Перед разработчиками всегда будет ставиться задача по созданию компонентов для других разработчиков команды или организации. Прилагаемая к компоненту документация помогает прояснить то, как и когда использовать компонент, и снижает общие затраты на поддержку. Создание документированного компонента включает несколько шагов:

Создание компонента
Создание XML файла
Тестирование компонента в сценарии развертывания

Шаг 1, создание компонента

Поначалу название этого шага может звучать пугающе, примерно как указание “снимите крышу, отложите” в качестве шага 1 в плане реконструкции вашего дома. Однако процесс создания компонента хорошо описан в нескольких разборах программ, приведенных в MSDN Library & VS documentation; поэтому мы не будем на этом останавливаться, а возьмем простой пример и используем его, чтобы показать, как добавить XML документацию.

Окончательной целью этого пошагового руководства является создание двух файлов. Первый - .DLL, которую будет использовать потребитель компонента; второй - .XML файл, содержащий всю документацию для этого компонента. Структура компонента-образца следующая:

using System;

namespace XMLDeploy1
{
  public class Temperature
  {
    public static int CelsiusToFahrenheit(int degreesCelsius)
    {
      return ((int)((9/5)*degreesCelsius) + 32);
    }
	
    public static int FahrenheitToCelsius(int degressFahrenheit)
    {
      return ((int)((5/9)*(degressFahrenheit - 32)));
    }
  }
}

Обратите внимание, что в компоненте пропущена очень важная часть – документация! Несмотря на сравнительную простоту компонента, в нем есть три момента, где добавленная документация будет чрезвычайно полезна для потребителя компонента. Эти три момента – это документация уровня класса, документация уровня метода и документация уровня параметра.

Чтобы добавить документацию уровня класса, наберите /// в строке над

public class Temperature

Затем между автоматически сгенерированными тегами <summary> опишите то, для чего предназначен класс Temperature. Например:

 
  /// <summary>
  /// Класс temperature предоставляет функции для преобразования 
  /// показаний различных шкал температур.  
  /// </summary>
  public class Temperature

Документация уровня метода и параметра примыкает к данному методу, так же как только что добавленная нами документация примыкала к классу. Например, давайте добавим комментарии к методу

 
public static int CelsiusToFahrenheit(int degreesCelsius)

Наберите /// перед описанием метода, обратите внимание, что при этом были автоматически сгенерированы и добавлены в исходный код три тега. Первый, <summary>, удобен для описания того, что делает метод. Второй, <param name=”degreesCelsius”>, используется для описания того, что необходимо передать в ‘degreesCelsius’. И третий тег, <returns>, подходит для описания возвращаемого значения метода. Документированный метод выглядит примерно так:

 
  /// <summary>
  /// Преобразовывает градусы Цельсия в градусы по Фаренгейту
  /// </summary>
  /// <param name="degreesCelsius">Degrees Celsius</param>
  /// <returns>Возвращает градусы по Фаренгейту</returns>
  public static int CelsiusToFahrenheit(int degreesCelsius)

После применения этих же шагов для создания документации уровня метода и параметра ко второму методу класса, наш пример выглядит так:

using System;

namespace XMLDeploy1
{
  /// <summary>
  /// Класс temperature предоставляет функции для преобразования 
  /// показаний различных шкал температур.  
  /// </summary>
  public class Temperature
  {
    /// <summary>
    /// Преобразовывает градусы Цельсия в градусы по Фаренгейту
    /// </summary>
    /// <param name="degreesCelsius">Degrees Celsius</param>
    /// <returns> Возвращает градусы по Фаренгейту </returns>
    public static int CelsiusToFahrenheit(int degreesCelsius)
    {
      return ((int)((9/5)*degreesCelsius) + 32);
    }
	
    /// <summary>
    /// Преобразовывает градусы по Фаренгейту в градусы Цельсия
    /// </summary>
    /// <param name="degressFahrenheit">Degrees Fahrenheit</param>
    /// <returns> Возвращает градусы Цельсия</returns>
    public static int FahrenheitToCelsius(int degressFahrenheit)
    {
      return ((int)((5/9)*(degressFahrenheit - 32)));
    }
  }
}

Шаг 2, создание XML файла

Теперь, когда в компонент добавлены все комментарии, пришло время генерировать .XML файл, содержащий всю информацию документации. IntelliSense будет использовать этот файл для генерирования всплывающих подсказок для компонента.

Чтобы создать XML файл, откройте “Solution Explorer”, щелкните правой кнопкой проект и выберите “Properties”. В открывшемся диалоговом окне выберите “Build” в папке “Configuration Properties”.

Рисунок 1. Solution Explorer

Обратите внимание на свойство “XML Documentation File”. Введите имя .XML файла, который должен быть сгенерирован.

Комментарий: это имя должно быть таким же, т.к. .DLL или IntelliSense не смогут найти его.

Пересоберите приложение.

Шаг 3, тестирование компонента в сценарии развертывания

Создайте новый проект, чтобы протестировать только что созданный компонент с включенными XML комментариями. После создания проекта, щелкнув правой кнопкой проект в solution explorer и выбрав ‘add reference’ в контекстном меню, откройте диалоговое окно ‘add references’. Щелкните кнопку ‘browse’ и найдите .DLL компонента, который мы только что создали. Выберите этот файл и щелкните ok. Этим вы добавите в тестовом проекте ссылку на компонент, созданный в шаге 1. При добавлении ссылки в директорию “bin” тестового приложения копируются .DLL и .XML файл (.XML файл и .DLL должны находится в одной директории, или будет скопирован только .DLL). Теперь IntelliSense будет разбирать XML файл и предоставлять потребителю всплывающие подсказки.

Рисунок 2. Всплывающие подсказки.

Также VS ObjectBrowser сможет теперь видеть компонент и ассоциированную с ним документацию:

Рисунок 3. Инспектор объектов.

Справочник тeгов

Рекомендуемые XML теги:

Tag	Назначение
<c>	Устанавливает шрифт текста таким же, как и шрифт кода
<code>	Устанавливает одну или более строк исходного кода или выходных данных программы
<example>	Обозначает пример
<exception>	Определяет исключительные ситуации, которые может формировать метод
<list>	Создает список или таблицу
<para>	Разрешает добавить структуру к тексту
<param>	Описывает параметр метода или конструктора
<paramref>	Показывает, что слово является именем параметра
<permission>	Документирует возможность безопасного доступа члена
<remarks>	Описывает тип
<returns>	Описывает значение, возвращаемое методом
<see>	Определяет связь
<seealso>	Генерирует раздел See Also
<summary>	Описывает член типа
<value>	Описывает свойство

Таблица 1. Список предопределенных тегов.

Тег: <c>

Этот тег обеспечивает механизм индикации того, что шрифт фрагмента текста описания должен быть таким же, какой используется в блоке кода. (Для строк кода используйте <code>)

Синтаксис:

<c>текст который будет отформатирован так же как и код</c>

Пример:

/// <remarks>Класс <c>Point</c> моделирует координаты точки в 2-х
/// мерном пространстве.</remarks>
public class Point 
{
  // …
}

Тег: <code>

Этот тег используется, чтобы применить определенный шрифт к одной или более строкам исходного кода или выходных данных программы. (Для маленьких фрагментов кода в комментариях используйте <c>.)

Синтаксис:

<code>исходный код или программный вывод</code>

Пример:

/// <summary>Этот метод изменяет положение точки
/// на  x- и y-смещения.
/// <example>Например:
/// <code>
///	Point p = new Point(3,5);
///	p.Translate(-1,3);
/// </code>
/// результат в  <c>p</c>будем иметь значения (2,8).
/// </example>
/// </summary>
public void Translate(int xor, int yor) 
{
  X += xor;
  Y += yor;
}

Тег: <example>

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

Синтаксис:

<example>описание</example>

Пример:

Пример смотрите <code>.

Тег: <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();
    // …
  } 
}

Тег: <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
{
  /// <remarks>Пример маркированного списка:
  /// <list type="bullet">
  /// <item>
  /// <description>Item 1.</description>
  /// </item>
  /// <item>
  /// <description>Item 2.</description>
  /// </item>
  /// </list>
  /// </remarks>
  public static void Main () 
  {
    // …
  }
}

Тег: <para>

Этот тег предназначен для использования в других тегах, таких как <remarks> или <returns>, и разрешает добавление структуры в текст.

Синтаксис:

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

Тег: <param>

Этот тег используется для описания параметра метода, конструктора или индексатора.

Синтаксис:

<param name="name">description</param>

name – Имя параметра.

description – Описание параметра.

Пример:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <param><c>xor</c> is the new x-coordinate.</param>
/// <param><c>yor</c> is the new y-coordinate.</param>
public void Move(int xor, int yor) 
{
  X = xor;
  Y = yor;
}

Тег: <paramref>

Этот тег используется как признак того, что данное слово является параметром. Файл документации может быть обработан так, чтобы отформатировать этот параметр некоторым определенным способом.

Синтаксис:

<paramref name="name"/>

name – Имя параметра.

Пример:

/// <summary>This constructor initializes the new Point to
///	(<paramref name="xor"/>,
/// <paramref name="yor"/>).</summary>
/// <param><c>xor</c> is the new Point's x-
/// coordinate.</param>
/// <param><c>yor</c> is the new Point's y-
/// coordinate.</param>
public Point(int xor, int yor) 
{
  X = xor;
  Y = yor;
}

Тег: <permission>

Этот тег разрешает документирование возможности безопасного доступа к члену.

Синтаксис:

<permission cref="member">description</permission>

cref="member" – Имя члена. Генератор документации проверяет существование данного элемента кода и преобразовывает член в имя канонического элемента в файле документации.

description – Описание доступа к члену.

Пример:

/// <permission cref="System.Security.PermissionSet">Everyone can
/// access this method.</permission>
public static void Test() 
{
  // …
}

Тег: <remarks>

Этот тег используется для включения обзорной информации о типе. (Для описания типа членов используйте <summary>.)

Синтаксис:

<remarks>description</remarks>

description – Текст комментариев.

Пример:

/// <remarks>Class <c>Point</c> models a point in a two-dimensional 
/// plane.</remarks>
public class Point 
{
  // …
}

Тег: <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, training, or embedded 
/// whitespace.</returns>
public override string ToString() 
{
  return "(" + X + "," + Y + ")";
}

Тег: <see>

Этот тег обеспечивает возможность задавать связь в тексте. (Для обозначения текста, который должен появиться в секции See Also, используйте <seealso>.)

Синтаксис:

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

Тег: <seealso>

Этот тег обеспечивает возможность генерировать элемент для секции See Also. (Используйте <see> для задания связи из текста.)

Синтаксис:

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

Тег: <summary>

Этот тег может использоваться для описания члена для типа. (Используйте <remarks> для описания самого типа.)

Синтаксис:

<summary>description</summary>

description – Краткое описание члена.

Пример:

/// <summary>This constructor initializes the new Point to 
/// (0,0).</summary>
public Point() : this(0,0) 
{
}

Тег: <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; }
}