Обзор Documentation Insight Enterprise v.2.6.

Периодически на WebDelphi появляются статьи, посвященные каким-либо инструментам для более комфортной работы в Delphi, например, «Обзор инструмента CodeSite» или «Опыт работы с madExcept«. В одном из таких постов я затрагивал вопрос о документировании исходного кода в Delphi XE2 и рассмотрел возможности инструмента Documentation Insight Express. Сегодня будут рассмотрены возможности уже полноценной Documentation Insight Enterprise, которую можно приобрести за отдельную плату на сайте DevJet.

Первое, что отличает Enterprise-версию от Express — это редактор документации. В Enterprise — это уже полноценный WYSIWYG-редактор с дополнительными полями, такими как «Examples», «See Also» и т.д.:

Редактор Express-версии

Редактор Enterprise-версии

 При этом ссылки можно вставлять не только на какие-то внешние ресурсы (сайты), но и на объекты в исходнике или типы данных для чего имеется отдельное окно:

Окно вставки гиперссылки в документацию

Также, в Express-версии присутствует такое ограничение как невозможность документирования непубличных свойств и методов. Соответственно, в Professional- и Enterprise-версии этого ограничения нет.  В целом, редактор Document Insight довольно простой и одновременно функциональный.

Следующее отличие Enterprise-версии — это набор настроек инструмента. Проверка орфографии — это мелочь, хоть и приятная,  а вот использование стилей оформления документации — возможность полезная. Особенно для обладателей старых версий Delphi. Вообще, сворачивание блоков с XML-документацией, если я не ошибаюсь, появилась только в RAD Studio XE2, т.е. кусок документации вот такого вида:

Стало возможно свернуть вот до такого вида:

Удобно, особенно, когда в модуле содержится много документации — свернул блоки и работай спокойно (плохо только, что форматировщик исходного кода все блоки снова разморацивает).  А как быть обладателям, скажем Delphi XE или 2010? Разработчики Documentation Insight решили проблему сворачивания блоков документации довольно просто и удобно — с использованием вставки {$REGION}. В настройках Documentation Insight имеется вкладка Styles, которая содержит следующий набор опций:

Настройка стилей обрамления блоков документации

Здесь мы можем воспользоваться либо «родным» для XE2 стилем, т.е. без какого-либо обрамления, либо использовать REGION и при этом делать подписи этим регионам либо фиксированной строкой (по умолчанию — это строка «Documentation»), либо вытаскивать подпись из тега summary, например, вот так:

Способы сворачивания блоков документации

Следующее отличие Enterprise-версии от Express — это Documentation Explorer.

Documentation Explorer позволяет просматривать всю документацию по проекту без предварительной её сборки в xml или html-файлы. На примере того куска документации, что показана на изображении выше, Documentation Explorer будет выглядеть следующим образом:

Слева в Explorer’е собраны все модули и классы проекта. При этом не обязательно, чтобы в исходнике была какая-нибудь документация — Documentation Insight покажет в дереве все, что найдет. Справа показана то, как будет выглядеть документация после сборки. Не выходя из Explorer’а можно выбрать любой объект в дереве и написать для него документацию. Например, я создал описание для кнопки на форме:

Документирование исходного кода в Explorer

В общем, Documentation Explorer удобная штука,  не надо прыгать по разным модулям — открыл окно Explorer’а и сиди документируй сколько хочешь.

Двигаемся дальше. А дальше самое важное — создание файлов документации.  Когда я рассматривал возможности Documentation Insight Express, то в качестве альтернативы (не самой удачной) говорил, что собрать документацию с помощью инструмента Model View. В Documentation Insight Enterprise генератор документации может создать справку в трех форматах:

1. Набор HTML-файлов
2. CHM-справка
3. HxS-файл для Microsoft Help 2.x

Для того, чтобы собрать файлы справки используется отдельный помощник, который вызывается из главного меню (опция Generete Documentation ). В настройках мы можем указать основную информацию о проекте:

Генератор документации

Если необходимо, то также мы можем указать генератору документацию из каких проектов в группе нам необходимо собрать:

указать «шапку» и «подвал» для страниц документации:

и указать в каких форматах собирать документацию:

Собранная Documentation Insight документация выглядит так:

В общем и целом мое мнение о Documentation Insight осталось прежним — отличный инструмент с достаточным набором возможностей для создания удобной справки по исходному коду проекта.

Остается только добавить один момент, о котором сообщил в комментариях к предыдущему посту о Documentation Insight Александр Алексеев — установка расширенного шаблона для Help Insight.

Скачать расширенный шаблон можно отсюда. Что он нам даст в итоге. Конечно же большее удобство работы :) Например, возьмем вот такой блок документации:

Без расширенного шаблона для Help Insight подсказка будет выглядеть вот так:

Теперь скачиваем шаблон и распаковываем архив в директорию:

• RAD Studio 2007 or 2009: {$BDS}\ObjRepos
• RAD Studio 2010 or XE-XE2:  {$BDS}\ObjRepos\en

И Help Insight теперь будет выглядеть совсем иначе. Вот так:

Скажем за эту красоту спасибо Александру и Marco Cantu и пойдем дальше работать :). Всем удачи и до новых встреч на страницах WebDelphi.ru

Книжная полка

	Автор: Дмитрий Осипов Название: Delphi. Программирование для Windows, OS X, iOS и Android Описание Подробно рассматривается библиотека FM, позволяющая создавать полнофункциональное программное обеспечение для операционных систем Windows и OS X, а также для смартфонов и планшетных компьютеров, работающих под управлением Android и iOS
	Автор: Андрей Шкрыль Название: Разработка клиент-серверных приложений в Delphi Описание: Рассмотрены практические вопросы по разработке клиент-серверных приложений в среде Delphi 7 и Delphi 2005 с использованием СУБД MS SQL Server 2000, InterBase и Firebird. Приведена информация о теории построения реляционных баз данных и языке SQL. Освещены вопросы эксплуатации и администрирования СУБД.
	Автор: Антон Григорьев Название: О чем не пишут в книгах по Delphi Описание: Рассмотрены малоосвещенные вопросы программирования в Delphi. Описаны методы интеграции VCL и API. Показаны внутренние механизмы VCL и приведены примеры вмешательства в эти механизмы. Рассмотрено использование сокетов в Delphi: различные режимы их работы, особенности для протоколов TCP и UDP и др.
	Автор: Дмитрий Осипов Название: Delphi. Профессиональное программирование Описание: Книга рассчитана на подготовленного пользователя ПК, желающего самостоятельно научиться программировать и разрабатывать приложения и базы данных в среде Delphi. Опытные программисты смогут использовать издание как справочник. В тексте подробно описаны более 80 компонентов VCL, функции Object Pascal и Win32 API.
	Автор: Юрий Магда Название: Разработка приложений Microsoft Office 2007 в Delphi Описание: Описаны общие подходы к программированию приложений MS Office. Даны программные методы реализации функций MS Excel, MS Word, MS Access и MS Outlook в среде Delphi.