ошибка была исправлена. Это позволило бы отображать конечным пользователям все ошибки, исправленные в данной версии приложения, просто используя рефлексию для отыскания атрибутов BugFix и последующего сравнения номера версии данного исправления с версией, запрошенной конечным пользователем.

Этот подход прекрасно подошел бы для выпуска в конце цикла разработки документации, содержащей список всех исправлений, выполненных в последней версии. Конечно, в добавлении этих атрибутов приходится полагаться на разработчиков, но проверку документирования всех исправлений можно сделать частью цикла контрольного просмотра кода.

Резюме

В этой главе было описано, что собой представляют атрибуты, и были рассмотрены некоторые атрибуты, определенные внутри каркаса .NET Framework. Внутри каркаса определено множество других классов атрибутов, и лучший способ ознакомления с их применением - просмотр документации .NET Framework SDK. Чтобы выяснить все атрибуты, определенные в сборке, достаточно загрузить ее в утилиту Reflector, перейти к классу System. Attribute, а затем отобразить все производные типы. Количество атрибутов, определенных внутри каркаса .NET, может вызвать удивление.

В этой главе были рассмотрены следующие темы, связанные с атрибутами.

□ Использование атрибута Conditional для исключения кода отладки из двоичных файлов окончательного выпуска.

□ Использование атрибута Obsolete для пересмотра библиотек в будущем.

□ Использование атрибутов при сериализации для определения компонентов, подвергаемых и не подвергаемых сериализации.

□ Отложенное подписание сборки.

□ Способ создания пользовательских атрибутов.

Атрибуты - мощное средство добавления дополнительной информации в сборки. Они позволяют создавать собственные атрибуты и добавлять в классы необходимую дополнительную информацию. В этой главе было описано создание атрибута BugFix, который можно было бы использовать для связывания исправленного исходного кода с программной ошибкой, первоначально выявленной конечным пользователем. Существует также множество других применений атрибутов - поэтому настоятельно рекомендуется поискать другие классы атрибутов в каркасе .NET Framework.

XML-документация

До ЭТОЙ главы книги вы уже ознакомились с языком С# в целом, а также с множеством задач, которые можно выполнять с его помощью, в том числе - с программированием приложений для Web и Windows. В процессе чтения этих материалов интенсивно использовалось средство IntelliSense, доступное в Visual Studio. Это полезное средство радикально уменьшает трудоемкость ввода с клавиатуры, поскольку в процессе ввода предлагает ключевые слова, имена типов, имена переменных и параметры. Оно облегчает также запоминание имеющихся в распоряжении методов и свойств и часто явно указывает способ их использования.

Однако поддержка создаваемых классов реализована несколько хуже. Хотя программа и предлагает имена классов и их членов, какие-либо всплывающие подсказки о способе выполнения тех или иных задач отсутствуют. Для достижения поведения, аналогичного поведению типов каркаса .NET Framework, нужно применять XML-документацию. XML-документация позволяет включать описание синтаксиса, справку и примеры создаваемых классов на уровне исходного кода. Затем эту информацию можно использовать для предоставления информации IntelliSense средствам Visual Studio, как было описано ранее, но существуют также и другие возможности. XML-документацию можно применять в качестве исходной для создания полной MSDN-документации проектов. Кроме того, с помощью XSLT XML-документацию можно стилизовать для получения непосредственной HTML-документации, затрачивая при этом минимальные усилия. В предшествующих главах было показано, насколько гибким является язык XML, и все его возможности можно использовать в процессе разработки и эксплуатации приложений.

Документация особенно важна при работе в составе команды, поскольку позволяет подробно описать работу созданных типов. Она может быть также очень полезна конечным пользователям при создании комплектов средств разработки или аналогичных программных продуктов, когда предполагается, что пользователи будут применять созданные классы в собственном коде. Наличие средства встраивания этой документации в инструменты, используемые для разработки кода - очень мощная возможность. Хотя добавление XML-документации в код может быть процессом, тре-

бующим больших затрат времени, достигаемый результат вполне это окупает. Вставка поясняющего текста в процессе разработки может облегчать работу в долговременной перспективе и предоставляет удобную краткую справочную информацию, которая помогает избегать путаницы, когда количество классов в проекте начинает выходить из-под контроля.

В этой главе будут рассматриваться следующие темы.

□ Добавление и просмотр основной XML-документации.

□ Использование XML-документации.

Добавление ХМL-документации

Добавление XML-документации в код - поразительно простая задача. Как и атрибуты, рассмотренные в предыдущей главе, XML-документация может применяться к любому типу или члену за счет ее помещения в строках, предшествующих этому члену. Добавление XML-документации осуществляется посредством расширенной версии синтаксиса комментариев С#, в которой используются три косых черты вместо двух. Например, следующий код демонстрирует помещение XML-документации в файл исходного кода класса MyClass и метода MyMethod () этого класса:

/ (XML-документация располагается здесь.)

class MyClass {

/ (И здесь.)

public void MyMethodО

XML-документация не может применяться к объявлениям пространств имен.

Как правило, XML-документация будет занимать несколько строк, и помечаться в соответствии со словарем XML-документации:

/ <WLDocElement> III Содержимое. / Еще содержимое. / <IXMLDocElement>

class MyClass

В этом примере <XMLDocElement> - один из нескольких доступных элементов, который может содержать вложенные элементы, часть из которых могут использовать атрибуты для дальнейшего описания функциональных возможностей. Обратите внимание, что строки кода, помеченные символами /и содержащие XML-документацию, полностью игнорируются и обрабатываются как пробелы. Это необходимо, чтобы предотвратить обработку компилятором этих строк документации в качестве кода, что приводило бы к ошибкам компилятора.

Наиболее важный элемент XML-документации - <suminary>, который предоставляет краткое описание типа или члена. Прежде чем приступать к рассмотрению более сложных вопросов, необходимо ознакомиться со следующим примером, который иллюстрирует использование этого элемента и визуализацию результатов.