XML-комментарии

Каждый XML-комментарий в C#, начинается с трех слэшей «///», а в Visual Basic.NET с трех одиночных кавычек (апострофов) «' ' '». В C#, обычные комментарии начинаются с двух слэшей, а третий слэш говорит синтаксическому анализатору, что это XML-комментарий. В барсике, аналогично, только обычный комментарий начинается с одной, одиночной кавычки.

Для чего же нужны XML-комментарии? 

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

Сегодня, мы создадим процедуру, дадим ей описание, описание параметрам и добавим исключение. Когда мы будем вызывать нашу процедуру, IntelliSense будет показывать нам комментарии, которые мы написали.

Для примера будем использовать всего три тега:

  • Тег <summary>, в коде, встречается больше всего, т.к

он описывает элементы (члены) типа, включая методы, свойства и поля

  • Тег <param> описывает параметры метода или свойства. Имеет один атрибут Name = имя параметра
  • Тег <exception> описывает исключения, которые могут произойти. Атрибут cref = название исключения

Весь список тегов:

xml comment 300x151 XML комментарии

/// <summary>
/// Моя семья
/// </summary>
/// /// <exception cref="BrotherException">Описание</exception>
/// /// <exception cref="SisterException">Описание</exception>
/// <param name="I">Ваше имя</param>
/// <param name="Mam">Имя вашей мамы</param>
/// <param name="Dad">Имя вышего папы</param>
/// <param name="Sister">Имя вашей сестры</param>
/// <param name="Brother">Имя вашего брата</param>
static void MyFamily(string I, string Mam, string Dad, string Sister, string Brother)
 {
   // процедура
 }
''' <summary>
'''Моя семья
'''</summary>
''' <param name="I">Ваше имя</param>
''' <param name="Mam">Имя вашей мамы</param>
''' <param name="Dad">Имя вышего папы</param>
''' <param name="Sister">Имя вашей сестры</param>
''' <param name="Brother">Имя вашего брата</param>
Sub MyFamily(ByVal I As String, ByVal Mam As String, ByVal Dad As String, ByVal Sister As String, ByVal Brother As String)
    ' процедура
End Sub

Как будет показано в IntelliSense:

xml comment1 300x98 XML комментарии xml comment2 300x70 XML комментарии

Познакомиться с XML-комментариями, тегами и описанием можно на

  Метки: , , ,
  Евгений
  Просмотров: 12 214
  Запись опубликована в 08:52

Есть что сказать? Тогда действуй!


:wink: :twisted: :roll: :oops: :mrgreen: :lol: :idea: :evil: :cry: :arrow: :?: :-| :-o :-P :-D :-? :) :( :!: 8-O 8)