XML-документация по C#
Знаете ли вы, что при написании кода можно писать XML-документацию для проектов C#.NET? Документация программного обеспечения имеет решающее значение не только для приложений .NET, но и для всех программ. Разработчики .NET имеют возможность минимизировать задачу написания документации благодаря встроенной поддержке xml-документации.
В двух словах, вы можете превратить комментарии C# в XML-документацию .NET с простым изменением настроек.
Комментарии vs.XML Комментарии
Сначала давайте установим разницу между обычными комментариями .NET и XML-комментариями. Обычный комментарий — это быстрый фрагмент текста, который описывает, что делает строка кода, например:
|
1 |
int i = 10; //инициализация переменной |
Скучно, правда? Хотя эти комментарии очень полезны, они не полезны при создании документации для компонента или приложения. Вместо этого мы хотим использовать XML-комментарии.
Вместо этого XML-комментарии идут прямо перед функцией. Простой пример:
|
1 2 |
|
1 2 3 4 |
/// <summary> /// This function is great /// </summary> private static int getInt() |
Обратите внимание, что XML-комментарии xml-документации .NET начинаются с 3 косых черт вместо 2. Это типы комментариев, которые являются чистым золотом, когда дело доходит до документации. Наличие дополнительной информации о том, что делает функция, кроме ее имени, может значительно сэкономить время. Но на этом веселье не заканчивается, если есть параметры, то можно добавить описания к каждому из них:
|
1 2 3 4 5 |
/// <summary> /// This function is great /// </summary> /// <param name="myInt">This is the input integer</param> private static int getInt(int myInt) |
Xml-описания можно добавить для любого количества параметров. Также знайте, что вы также можете применять комментарии к классам.
Экспортная документация
При работе с функциями и классами, имеющими XML-документацию в проекте .NET, вы заметите, что документация немедленно применяется к IntelliSense. Поэтому, если XML-документация C# больше подходит для внутреннего проекта, вы можете просто сидеть сложа руки и наслаждаться удобством.
Но что делать, если вы хотите экспортировать библиотеку, например, которая будет использоваться в дальнейшей разработке .NET. К сожалению, XML-комментарии не компилируются автоматически вместе со сборкой. Необходимо указать Visual Studio создать специальный файл для хранения этих комментариев.
Для данного проекта перейдите в раздел Свойства > проекта [Имя проекта] …. Затем найдите вкладку «Сборка». Посмотрите внизу на флажок «ФАЙЛ XML-документации» и установите его. Введите имя файла документации.
После того, как у вас есть XML-файл, вам просто нужно убедиться, что он находится в той же папке, что и скомпилированная сборка. Тогда другие разработчики .NET увидят полезные XML-комментарии в intelliSense, даже если ваша библиотека скомпилирована.
Наличие всей документации в одном файле также дает возможность использовать другие средства для создания более сложных файлов чтения XML-документации .NET.