XML-документирование кода
При написании комментариев к коду приложения Calculator я использовал XML-комментарии. Для вставки XML-комментария достаточно трижды поставить знак слэша — ///, среда сама откроет тег, где уже можно вводить текст комментария. Использование такого способа документирования более удобно, чем обычное комментирование, — можно переносить слова на следующую строку без добавления знака комментария. Но самое главное — компилятор транслирует эти комментарии в отдельный XML-файл. Откройте окно Solution Explorer проекта Calculator и щелкните правой кнопкой на его названии. В появившемся контекстном меню выберите пункт Properties. На вкладке Configuration Properties/Build (см. рис. рис. 1.24) в поле XML Documentation File введите название выходного файла — CalcDescription.xml. Скомпилируйте приложение. Запустите проводник Windows (клавиша Windows+E) и перейдите в папку, содержащую проект Calculator. В ней появился созданный нами файл CalcDescription.xml, содержимое которого представляет собой обычный XML- документ:
Листинг 1.10.
(html, txt)
Файл получается довольно длинным, и читать его в таком формате неудобно, хотя и возможно. Однако XML-код можно преобразовать в HTML, написав XSLT-файл. Кроме того, XML-документ можно сохранить в специальной базе данных для документации.
Документирующие комментарии можно преобразовать в чрезвычайно удобную форму, сгенерировав в среде Visual Studio .NET отчет Code Comment Web Report. Выберите пункт меню Tools/Build Comment Web Pages. Результатом будет набор HTML-файлов, которые можно просмотреть непосредственно в Visual Studio .NET или с помощью браузера, перейдя в сформированную папку CodeCommentReport (рис. 1.48):
увеличить изображение
Рис. 1.48. Страница отчета
Для увеличения функциональности создаваемого отчета при XML-документировании кода можно использовать стандартные теги. Подробное обсуждение этих вопросов выходит за рамки этой книги.
Полный список тегов можно найти в документации, входящей в комплект Visual Studio .NET.
Листинг 1.10.
Файл получается довольно длинным, и читать его в таком формате неудобно, хотя и возможно. Однако XML-код можно преобразовать в HTML, написав XSLT-файл. Кроме того, XML-документ можно сохранить в специальной базе данных для документации.
Документирующие комментарии можно преобразовать в чрезвычайно удобную форму, сгенерировав в среде Visual Studio .NET отчет Code Comment Web Report. Выберите пункт меню Tools/Build Comment Web Pages. Результатом будет набор HTML-файлов, которые можно просмотреть непосредственно в Visual Studio .NET или с помощью браузера, перейдя в сформированную папку CodeCommentReport (рис. 1.48):
увеличить изображение
Рис. 1.48. Страница отчета
Для увеличения функциональности создаваемого отчета при XML-документировании кода можно использовать стандартные теги. Подробное обсуждение этих вопросов выходит за рамки этой книги.
Полный список тегов можно найти в документации, входящей в комплект Visual Studio .NET.
