Релиз RD Studio XE2 принес нам довольно много новинок на рассмотрение и проверку работоспособности/важности/необходимости которых у нас, видимо, уйдет весь промежуток времени до релиза XE3. Нововведения типа платформы Firemonkey или механизма LiveBindings сейчас на слуху у многих. Но не стоит забывать и про такие, пусть и не сильно заметные, но тем не менее полезные нововведения как, например, инструмент Documentation Insight. Про нечто подобное этому инструменту я говорил не далее как 27 апреля 2010 года в статье для конкурса на DelphiFeeds.ru, тема которого тогда была «Чего не хватает в Delphi?» И вот моя «хотелка» сбылась — в Delphi XE2 появился довольно удобный инструмент для создания и просмотра документации исходного кода.
Вначале небольшое введение в документирование кода в Delphi.
Документирование кода в Delphi.
Если не рассматривать всякого рода сторонние инструменты для создания документации к вашим исходникам, например, Doc-O-Matic, PasDoc и т.д., то «из коробки» нам остается создание документации на основе XML. Смысл такого документирования заключается в следующем: над элементом код, которые необходимо отразить в документации (класс, метод, переменная и т.д.) помещается специальный блок, каждая строка которого начинается с тройного слэша (///). В этом блоке располагаются XML-теги, содержащие какую-либо информацию по элементу (описание, значения переменных, ссылки на другие разделы документации и т.д.). Например, так можно сделать небольшой описание для класса формы:
На текущий момент, в Delphi XE2 используются следующие XML-теги для формирования документации:
- summary — краткое описание функции или класса
- para — тег, используемый для задания нового параграфа
- c — используется для задания создания моноширинного текста
- code — преформатированный текст, например, исходный код
- remarks — замечания к функции или классу
- param name=»ParameterName» — описание параметра с названием ParameterName
- see — дополнительные источники информации по элементу кода
- returns — описание возвращаемых значений
- exception cref=»EExceptionTypeName» — исключения, которые могут быть сгенерированы в результате работы метода
- permission cref=»PermissionType» — разрешения метода
Documentation Insight в Delphi XE2
Но и этого, думаю, вполне достаточно для небольших проектов, чтобы создать необходимую документацию для исходника. Ограничения редактора Documentation Insight никак не отражаются на работе вьювера. То есть, если я ручками добавлю в справку, например, вот такие теги:
Создание HTML-документации проекта
Как я говорил выше, на основе нашей XML-разметки для документации исходника можно также генерировать и HTML-справку. Сделать это довольно просто, используя инструмент Model View.
Алгоритм создания HTML-документации в этом случае может быть таким:
1. Создаем необходимые описания классов и методов в исходнике
2. В Project Manager переключаемся на вкладку Model View и соглашаемся включить поддержку моделирования.
3. В открывшемся окне выбираем наш проект и жмем Ok:
Теперь вкладка Model View будет выглядеть так:
4. Жмем в окне Model View правую кнопку мыши и в меню выбираем Generate Documentation:
5. В новом окне выбираем путь к документации, необходимые опции и жмем Ok:
В результате в выбраной директории будут сформированы необходимые файлы HTML-документации, которую можно будет просмотреть в браузере. Выглядеть справка по умолчанию будет так:
Конечно, использовать инструмент моделирования исключительно для того, чтобы сгенерировать HTML-справку — это крайне нерационально, т.к. этот инструмент имеет на порядок больше полезных функций и заслуживает отдельного внимания, но приведенный выше способ создания документации наиболее простой.
Что же касается самой HTML-справки, которую генерирует инструмент Delphi, то тут я, прямо скажу, не в восторге. По сравнению с тем же Doc-O-Matic документация содержит много лишнего, да и графика страдает. Поэтому этим способом создания HTML-документации я в принципе не пользуюсь. А вот Modeling периодически использую, особенно, когда в руки попадает чужой код, но это уже совсем другая история…
В заключение скажу, что новый инструмент Documentation Insight мне понравился даже включая во внимания его урезанную версию. Вполне работоспособный и удобный инструмент для документирования кода. Если разживусь на лишний рубль (а точнее 3к рублей) может даже и платную версию как-нибудь приобрету, если возникнет острая необходимость получить дополнительные «плюшки» для работы, но это всё мечты.
Как Вам новый инструмент? Планируете использовать его в дальнейшей работе?
Книжная полка
 |
Описание Подробно рассматривается библиотека FM, позволяющая создавать полнофункциональное программное обеспечение для операционных систем Windows и OS X, а также для смартфонов и планшетных компьютеров, работающих под управлением Android и iOS
|
 |
 |
Описание: Рассмотрены практические вопросы по разработке клиент-серверных приложений в среде Delphi 7 и Delphi 2005 с использованием СУБД MS SQL Server 2000, InterBase и Firebird. Приведена информация о теории построения реляционных баз данных и языке SQL. Освещены вопросы эксплуатации и администрирования СУБД.
|
|
 |
Название: О чем не пишут в книгах по Delphi
Описание: Рассмотрены малоосвещенные вопросы программирования в Delphi. Описаны методы интеграции VCL и API. Показаны внутренние механизмы VCL и приведены примеры вмешательства в эти механизмы. Рассмотрено использование сокетов в Delphi: различные режимы их работы, особенности для протоколов TCP и UDP и др.
|
|
 |
Описание: Книга рассчитана на подготовленного пользователя ПК, желающего самостоятельно научиться программировать и разрабатывать приложения и базы данных в среде Delphi. Опытные программисты смогут использовать издание как справочник. В тексте подробно описаны более 80 компонентов VCL, функции Object Pascal и Win32 API.
|
|
 |
Описание: Описаны общие подходы к программированию приложений MS Office. Даны программные методы реализации функций MS Excel, MS Word, MS Access и MS Outlook в среде Delphi.
|
|
Спасибо.
Ограничения встроенной в среду утилиты проявляются не только в урезанном наборе тегов. Также, не разрешается документировать приватные разделы классов. Впрочем, это ограничение легко обойти временно объявив все секции как public.
А вот из доступных возможностей хочется упомянуть еще возможность документирования перечислимых типов. В этом случае помимо summary и remarks можно описать каждое принимаемой переменной типа значение.
Help Insight есть в Delphi давно. Не уверен, есть ли он в D2005, но в D2006 — точно. Кстати, туда можно установить расширенный шаблон от Documentation Insight.
Александр, я же с Delphi 7 сразу на 2009 перелез, поэтому по части Insight’ов точно сказать не могу. О! Я смотрю ты прямо НАД Марком Кэнту там в «Credits» стоишь — молодец! =)
Как всегда спасибо за статью Влад. Может мелочь, но при переключении в Project Manager на Model View у меня ни когда ни чего не происходило, пока явно не сказать через меню Project-Modeling Support и уже там подключить проект. ИМХО конечно, да и денег стоит, но, что касается управлением классов и всего ООП однажды попробовав modelmaker code explorer на другое уже больно смотреть :) А так, Documentation Insight один из главных факторов моего был, на переход к XE2.
Дима, не за что =). Странно, что в новом проекте при переключении на Model View ничего не происходит. У меня, например, всегда Delphi спрашивает подключать Modiling Support или нет. Ну да ладно — это мелочь, решаемая через главное меню.
Ну это да, ну так, мало-ли у кого так-же, что-бы сразу знать кудымс ткнуться :)
Прошу прощения Влад и у всех читающих, решил перепровериться, создал новый проект и при переключении спрашивает о моделировании, если отказаться, то больше и не будет спрашивать… я на примере твоей статьи начал на предыдущем проекте и видимо когда-то отказался… вот блин… век живи век учись….
Тынц.
Кстати, Влад, у тебя некорректно работает кнопка для вставки ссылок в комментах. Там что-то с текстом.
Ыааа! Да тут вообще форма фигова пашет. Я-то через админку отвечаю — не вижу ничего. Александр, спасибо, что подсказал. Счас попробую исправить глюк с комментариями.
Идея документирования хорошая, но сделана топорно. Порочна сама идея размещать документирование в коде. Раз есть доступ к объектам модуля — классам, свойствам, методам, — то модифицировать модуль вставками совершенно излишне. Данные уже хранятся в памяти! Об этом свиделельствует кнопка сохранения и настройка автосохранения. Значит надо просто сбрасывать их в отдельный файл с другим расширением. Лучше всего в формате xml. Если получится сделать совместимость с проектами Help & Manual — лучшего и не пожелаешь. Есть интеграция со справкой IDE, но нет возможности сделать отдельный проект справки. Явное упущение! Также вставленные в текст кода блоки с документацией корежат его структуру. Я проверил… Подробнее »
Кстати, есть идея реализовать альтернативный продукт такого рода. Думаю, добротный пилотный проект возможен в течение пары месяцев. Свою кандидатуру не предлагаю, потому что шеф такого задания пока не придумал мне. многогрешному. А в народ кинуть мысль стоит, может найдет своего Моцарта
как в TXMLDocument задать пропуск перед зыкрытием тега?
в xml сгенерированной какой-то программой одиночные, пустые теги закрываются с пробелом перед косой чертой [code][\code]
Есть прекрасный инструмент для документирования — JavaDoc. Проверенный временем, не особо перегружающий код. PasDoc — немного корявенький аналог для Delphi. Почему нельзя было развить и «узаконить» нормальный продукт? С XML — это же ужасс. Да ещё и «не разрешается документировать приватные разделы классов»… С какого перепуга *инструмент* накладывает ограничения? Прибавим такое ограничение XML, как регистрозависимость — и составление такой документации окончательно превращается в обезьянью работу. Я всеми руками за внутреннее документирование исходников, постоянно к этому даже принуждаю — но я против таких затрат.