Приемы, рецепты и полезные советы по C#. Урок 2. Автоматизированное создание документации в Visual Studio 2010.
В Visual Studio 2010 есть возможность автоматически создавать документацию из комментариев к классам и их методам. Для того, что бы возможно было создавать документацию, комментарии необходимо начинать не с "//", а с "///", при чем в комментариях используются специальные тэги. Вот пример такого вот комментария:
|
/// <summary> /// Мой пробный класс /// </summary> public class MySampleClass { /// <summary> /// Мой пробный метод. Он выводит сообщения /// </summary> /// <param name="str">Сообщение, которое выводит мой пробный метод</param> public void MySampleMethod(String str) { MessageBox.Show(str); } } |
Что нам дают такие комментарии? Во первых, если мы используем созданный класс, то автоматически получаем о нем подсказки*:
Если выбираем метод класса, так же получаем о нем подсказки*:
Если заполняем аргументы метода, так же получаем подсказки*:
Круто, не правда ли? Но это еще не все. Мы можем при компиляции сгенерировать XML-файл документации. Для этого нам нужно зайти в свойства проекта*:
Переключаемся на закладку "Построение" и где то внизу (прокрутите скроллер) увидим возможность включить генерацию XML-документации*:
Теперь при компиляции у нас будет сгенерирован файл (по умолчанию он кладетсян в ту же папку, что и экзешники):
Как видим, наши комментарии попали в файл документации:
Встает вопрос, а для чего вообще нужна такая XML-документация? Во первых, если вы распространяете свои библиотеки без исходным кодов, то формирование XML-документации необходимо, что бы у пользователя отображались подсказки. Без XML-документации пользователь просто не увидит этих подсказок.. А во вторых, XML - документацию можно скомпилировать и превратить в chm-файл (полноценный файл справки):
Но как скомпилировать такой файл справки, я расскажу в будущих уроках.
Скриншоты, помеченные знаком *, являются цитатами и иллюстрациями программного продукта "Microsoft Visual Studio 2010 Professional", авторское право на который принадлежит корпорации Microsoft..