Разработчик любого большого проекта на Delphi рано или поздно сталкивается с потребностью в документировании кода, начиная от банальных комментариев к классам/методам и заканчивая полноценным help-файлом (html, chm, hlp или даже майкрософтовским Help 2.0). Для тех кто пишет на Java или C# это уже давно не проблема — у них есть JavaDoc и Sandcastle. На Delphi ситуация была сложной вплоть до выхода 2005-ой версии, в которой, наконец, добавили встроенную поддержку XML-документации.
Хотя и сейчас, глянув исходники разных проектов, чего только не увидишь. Наиболее часто используется javadoc-овский стиль (видимо, для бесплатного DelphiDoc). Вот как выглядят комментарии в его формате:
{** Open all tables that is marked for opening
@param FastOpen Use the fast opening routine
@return Returns True if Ok
@see TMainForm }
function TMainForm.OpenTables(FastOpen: Boolean): Boolean;
begin
...
...
end;
Сгенерированные на основе таких комментариев хэлпы выглядят более-менее прилично. Но в отличие от тех же Eclipse или Netbeans, для которых такой формат как родной, для среды Delphi это дикость. Составлять такие конструкции без какой-либо помощи IDE довольно утомительное дело. Как ни старайся, текст “Open all tables that is marked for opening” не появится во всплывающей подсказке и программисту каждый раз придётся смотреть в исходник или лезть в хэлп.
Help Insight
Начиная с версии 2005, в Delphi введен новый тип подсказок в редакторе кода — Help Insight. Теперь это уже не те жалкие tooltip-ы, которые были в старых версиях.
Help Insight в действии
Жаль конечно, что CodeGear (а за ним и Embarcadero) не удосужились сделать подробные комментарии для Help Insight ко всем стандартным модулям. Наверное, им просто лень лезть во все исходники, многие из которых почти без иземений остались от самых древних версий Delphi. Но дело не в этом. Главное, что эта фича дейтвительно работает, а раз работает, то будем её использовать.
XML комментарии
С этим форматом, наверное, знакомы все кто так или иначе сталкивался с разработкой на .NET. Именно такой формат поддерживает вышеупомянутый Help Insight, и вот как он выглядит:
/// <summary>
/// Open all tables/b that is marked for opening. See also
/// <see cref="TMainForm"/> class.
/// </summary>
/// <param name="FastOpen">Use the fast opening routine.</param>
/// <returns>True if ok; otherwise, False.</returns>
function TMainForm.OpenTables(FastOpen: Boolean): Boolean;
begin
...
...
end;
Несложно догадаться, что тэг summary — это описание метода, param — описание параметров, returns — описание возвращаемого значения, а see — ссылка на другое описание. Список всех тэгов можно посмотреть в MSDN (в хэлпах Delphi 2007 и 2009 никакой информации по этому поводу мне найти не удалось). Более того, кроме стандартных тэгов можно использовать некоторые из HTML, к примеру <b> или <i> для выделения важных замечаний. Для написания таких комментариев удобно пользоваться шаблоном — наберите в тексте программы “summary” и нажмите клавишу Tab. В Delphi 2009 вам даже не придётся самостоятельно набирать три слэша в начале — по нажатию Enter они добавяся автоматически как в Visual Studio (это также срабатывает и в Delphi 2007 SP3). Стоит упомянуть, что XML комментарии можно писать в объявлениях классов, процедур, функций, типов и даже переменных.
Чтобы увидеть написанные комментарии в действии, нужно зайти в окно настроек проекта (Project — Options) и на вкладке Compiling отметить галочкой (или выставить в True в Delphi 2009) пункт Generate XML documentation. После каждой компиляции проекта Delphi сгенерирует несколько XML файлов (один на проект и по одному на каждый модуль) которые будут содержать все XML комментарии. Эти файлы можно будет использовать для создания справочной системы. Но главное, что теперь вот такой удобный мини-хэлп будет отображаться во всплывающих подсказках:
К сожалению, HTML тэги в Help Insight не срабатывают, зато все ссылки работают на ура.
Генерация документации средствами Delphi
В Delphi 2005—2009 есть 2 способа создания документации. Мы испробуем на деле оба. Первый, и самый простой, реализован средствами встроенного в IDE Together. Сохраните проект, и кликните по пункту меню View — Model View. Delphi может спросить, добавлять ли к проекту modeling support, выбирайте «да». Откроется окошко Movel View в котором нужно выделить проект и в контекстном меню нажать Generate Documentation. Появится небольшое окошко с настройками (их на удивление мало), в котором сразу советую убрать галочки с Include Diagrams и Include Navigation Tree. Delphi немного потужится, и через пару секунд выдаст несколько HTML страничек.
Неожиданно, но получился классический хэлп полностью копирующий javadoc. Сначала восторг, но потом разочарование. При подробном рассмотрении обнаруживается, что он содержит много лишних невразумительных ссылок вроде default или globals, и в работе крайне не удобен. Все тэги <see> тупо вырезаются, так же как <b> или <i>. В описаниях классов и методов используются странные для Delphi понятия вроде Reintroduce, куда-то пропадают названия параметров. И в общем, полученный хэлп оказывается практически нечитабельным :( Такое впечатление, что разработчики просто не доделали эту функцию, а начали и оставили как есть.
Второй способ, как и многое в Delphi, не совсем очевиден — мы используем поставляемую вместе с IDE утилиту XMLDoc. Её можно найти в папке Мои документы\RAD Studio\<версия Delphi>\Demos\XMLDoc. Кроме того, вам потребуется установить Java SDK (1.4.2 или выше), Python (минимум 2.3) и Saxon (версия 6.5.5 for Java). После установки нужно будет добавить в системную переменную “Path” пути куда установлены Python и Saxon, например “C:\Python23\;C\Saxon655\” (это делается через «Мой компьютер», а в нём — «Переменные среды», пути нужно добавить через точку с запятой). В папке, куда вы распаковали Saxon, создайте BAT файл с именем saxon.bat с таким содержанием:
@java -jar "<путь к папке с Saxon>\saxon.jar" %1 %2 %3
Запускать его не нужно. В папке с XMLDoc-ом создайте BAT файл start.bat, чтобы не морочиться с командной строкой, и напишите в нём следующее:
cls xmldoc.py "<путь к папке с проектом>" pause
Пример пути — “C:\Projects\TestProject”. Важно: все используемые пути не должны содержать кириллицу, иначе у XMLDoc-а с ней будут проблемы. Итак, теперь всё готово, и можно запускать файл start.bat. Если всё пройдет успешно, то в папке с проектом появится папка doc, а в ней — final, в которой будут храниться HTML файлы сгенерированной документации. Вот что у меня получилось (на примере метода OpenTables):
По субъективной оценке данный вариант выглядит посимпатичнее первого. Вроде бы все замечательно, но усугубляет тот факт, что XMLDoc так же небрежно вырезал ссылку <see>. Нужно заметить что эти HTML файлы не окончательный вариант — их можно (и, по идее, нужно) преобразовать в формат Help 2.0 (их затем можно будет просматривать через Document Explorer, так же, как и хэлп в Delphi или Visual Studio). Для этого понадобится Visual Studio Help Integration Kit, а затем — CodeGear HelpKit. Так как у меня нервов больше не хватило, а результат уже в принципе понятен, я не стал идти дальше. Возвожно, вы окажетесь сильнее :)
Генерация документации с использованием Doc-O-Matic Express
Doc-O-Matic — довольно мощная утилита для создания документации на основе XML и JavaDoc комментариев в форматах HTML, CHM и Help 2.0. Но, к сожалению, полная её версия платная. Но не всё так плохо — есть версия Express (наверное подсмотрели название у Microsoft), а в ней есть почти всё что нужно. Её и опробуем.
С Doc-O-Matic не придется так много плясать с бубном, как с XMLDoc, но парой кликов тоже не обойдешься. Запустите утилиту, в разделе Project Files нажмите кнопку Add, в фильтре диалога выберите Delphi 2007 Project и откройте нужный файл проекта. Во вкладке HTML обратите внимание на раздел Files & Folders — в нём можно указать папку, куда будет помещён файл с документацией. Сохраните настройки в какое-нибудь удобоваримое место, намример в файл C:\mydoc.dox-express. Теперь закройте утилиту и зайдите в папку, куда установлен Doc-O-Matic. Создайте в ней BAT файл с такой строчкой:
domexpress.exe -config "HTML" "<путь к файлу *.dox-express>"
После выполнения этой команды файлы документации помещаются в заданную выше папку и автоматически запускается браузер. Вот как, например, будет выглядить описание к методу:
Опять же, субъективно, такой хэлп производит наиболее благоприятное впечатление. Нет лишних пунктов, удобная навигация. Немного портит впечатление отсутствие ссылки на слове “TMainForm”, но Doc-O-Matic хотя бы её не вырезал, в отличие от двух предыдущих утилит.
Вместо послесловия. Поддержка XML комментариев на уровне редактора кода в Delphi — отличная и удобная штука, и ей надо пользоваться. Но с генерацией документации дело обстоит сложнее: стандартные средства слишком сырые (и, чего душой кривить, кривые =), чтобы ими можно было без труда пользоваться. Но есть альтернатива в лице Doc-O-Matic Express, который справляется с этим делом весьма неплохо. Будем надеятся, что в скором времени (может быть и с выходом новых версий Delphi) появятся и новые, более гибкие утилиты.
Комментариев нет:
Отправить комментарий