XML документация в C#

Приветствую, хабра-дотнетчики!
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «XML документация» или «Документирующие комментарии XML». Это такие специальные теги XML, которые содержаться в комментариях и описывают свойства или методы в конкретном файле. Так вот, есть по крайней мере три веских причины, почему всегда следует заполнять XML комментарии.


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

А теперь мы рассмотрим теги, рекомендованные для использования. Для того, чтобы начать их вводить, нужно сначала поставить "///".

Тег	Используется для
<c>	одна строка исходного кода
<code>	много строк исходного кода
<example>	пример использования, можно использовать совместно с тегом <code>
<exception>	позволяет указать, какие исключения наш метод может выдавать
<include>	позволяет поставить ссылку на файл, в котором содержаться комментарии, используя XPath
<list>	обычный список
<para>	а это обычный параграф
<param>	описания параметра метода, каждый параметр описывается отдельно
<paramref>	позволяет указать, что слово внутри тега является параметром
<permission>	позволяет описать права доступа к методу
<remarks>	дополнительная информация, помимо тега <summary>
<returns>	описание того, что метод возвращает
<see>	позволяет указывать ссылки
<seealso>	текст в секции «Смотри также»
<summary>	общее описание
<value>	позволяет описывать свойства

Пример:

/// <summary>
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
/// </summary>
/// <param name="repeat">Сколько раз передать привет</param>
/// <returns>Сама строка с приветами</returns>
public string HelloHabr(int repeat)
{
     string result = "";
     for (int i = 0; i < repeat; i++)
     {
         result += "Hello, HabraHabr!\n";
     }
     return result;
}



А вот так наш метод будет показан в IntelliSense:



Подробно про все можно почитать как всегда на MSDN.

Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.