Pull to refresh

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

.NET *
Приветствую, хабра-дотнетчики!
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «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:

isense1.jpg - image uploaded to Picamatic
isense2.jpg - Picamatic - upload your images
Подробно про все можно почитать как всегда на MSDN.

Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.
Tags:
Hubs:
Total votes 52: ↑45 and ↓7 +38
Views 62K
Comments Comments 73