DocumentationInsight

До ХЕ2 вDelphi были такие инструменты как CodeInsightиHelpInsight, а теперь ещё появился и DocumentationInsight. Этот инструмент разработан в DevJETSoftware и предназначен для удобного просмотра и создания документации исходного кода.

Для вызова DocumentationInsght достаточно выбрать в главном меню Tools®Documentation InsightExpress®ShowDocumentation или же воспользоваться клавишами Ctrl+Shift+D. Для документации, представленной выше, окно DocumentationInsight будет выглядеть следующим образом:

Можнорасположить это окно, например, снизу в RAD Studio и иметь всегда под рукой удобный справочник по исходнику. DocumentationInsight показывает информацию по коду сразу же, как вы вызываете метод или создаете класс.

Чтобы создать документацию с помощью DocumentationInsight достаточно установить курсор на необходимый элемент кода и в окне инструмента выбрать вкладку Design:

В Express-версии DocumentationInsight имеется не такой большой размах по части возможных элементов справки. Всё, что можно сделать в редакторе по-умолчанию – это заполнить для описания класса теги summary и remarks, а для методов DocumentationInsightдает возможность заполнения тегов param, т.е. окно дизайнера будет выглядеть так:

Но и этого вполне достаточно для небольших проектов, чтобы создать необходимую документацию для исходника. Ограничения редактора DocumentationInsight Express никак не отражаются на работе вьювера. То есть, если вручную добавить в справку, например, вот такие теги:

то в итоге при просмотре документации на вкладке Preview отобразится такое описание метода:

Для оформления документации можно также использовать различные дополнительные теги, например seealso для вставки ссылок на сторонние ресурсы или другие разделы документации. Более подробно об XML-тегах для оформления документации можно почитать в справке к DocumentationInsight.

Платная версия DocumentationInsight стоит 99$ и дает в редакторе использовать все возможные теги для оформления документации.

Контрольные вопросы:

1. Что обеспечивает документирование кода?

2. Какой минимум документации должен быть включен в исходный код?

3. Что выполняют инструменты автоматического создания документации кода?

4. Что учитывается при выборе инструмента документирования кода?

5. Какие инструменты для написания справки Вы знаете?

6. На основе чего можно производить документацию кода в Delphi?

7. Как в коде помечаются блоки с XML-тегами?

8. Какие XML-теги используются в Delph для формирования документации? Что каждый из них описывает?

9. Как указываются XML-теги в коде приложения? Чем предваряется имя тега при закрытии соответствующего блока?

10. Какой инструмент Delphi формирует всплывающие подсказки на основе XML-документации в коде?

11. Какой инструмент Delphi позволяет сгенерировать HTML-справку по коду на основе XML-документации?

12. Какой инструмент Delphi предназначен для удобного просмотра и создания документации исходного кода на основе XML-тегов? Как вызывается этот инструмент?

13. Что необходимо сделать, чтобы создать документацию с помощью Documentation Insight?

14. Какие ограничения существуют в Express-версии Documentation Insight? Влияют ли эти ограничения на возможность просмотра документации по коду?

Лекция 20

ТЕМА:Создание системы помощи в программе.

Литература:Культин Н. Б. Основы программирования в Delphi 7. – СПб.: БХВ-Петербург, 2010.

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

1. Давать полное описание по вопросам использования программы.

2. Иметь графические материалы по вопросам использования программы.

3. Быть доступной для вызова из любой формы программы.

4. Иметь контекстные описания и удобную систему поиска информации.

5. Иметь минимально возможный размер.

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

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