Приветствую, хабра-дотнетчики!
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «XML документация» или «Документирующие комментарии XML». Это такие специальные теги XML, которые содержаться в комментариях и описывают свойства или методы в конкретном файле. Так вот, есть по крайней мере три веских причины, почему всегда следует заполнять XML комментарии.
Во-первых, такой подход позволяет стандартизировать комментарии в вашем проекте и, впринцепе, во всех проектах на C#, а стандарты в нашем деле это почти всегда хорошо. Во-вторых, IntelliSense будет автоматически отображать информацию о документированых методах и параметрах, также как и для методов, встроенных во фреймворк. Это очень сильно облегчит работу и сэкономит время и вам и другим разработчикам, работающим с вами. И в-третьих, на этапе компиляции можно сгенерировать XML файл, который будет содержать все комментарии в удобном формате, а с этим файлом уже можно сделать все что угодно.
А теперь мы рассмотрим теги, рекомендованные для использования. Для того, чтобы начать их вводить, нужно сначала поставить "///".
Пример:
А вот так наш метод будет показан в IntelliSense:
Подробно про все можно почитать как всегда на MSDN.
Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «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.
Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.
